stream-chat

What is stream-chat?

The stream-chat npm package is a powerful tool for building chat applications. It provides a comprehensive set of features for real-time messaging, user management, and chat room creation, among others. It is designed to be highly customizable and scalable, making it suitable for a wide range of applications from simple chat widgets to complex messaging platforms.

What are stream-chat's main functionalities?

Real-time Messaging

This feature allows you to send real-time messages in a chat channel. The code sample demonstrates how to initialize the StreamChat client, create a channel, and send a message.

const StreamChat = require('stream-chat').StreamChat;
const client = new StreamChat('api_key');

async function sendMessage() {
  const channel = client.channel('messaging', 'general', {
    name: 'General Chat',
  });
  await channel.create();
  await channel.sendMessage({
    text: 'Hello, world!',
    user_id: 'user123',
  });
}
sendMessage();

User Management

This feature allows you to manage users within the chat application. The code sample demonstrates how to create or update a user with specific attributes.

const StreamChat = require('stream-chat').StreamChat;
const client = new StreamChat('api_key');

async function createUser() {
  await client.upsertUser({
    id: 'user123',
    name: 'John Doe',
    role: 'user',
  });
}
createUser();

Channel Management

This feature allows you to manage chat channels. The code sample demonstrates how to create a new chat channel with a specific name and type.

const StreamChat = require('stream-chat').StreamChat;
const client = new StreamChat('api_key');

async function createChannel() {
  const channel = client.channel('messaging', 'general', {
    name: 'General Chat',
  });
  await channel.create();
}
createChannel();

Message Reactions

This feature allows users to add reactions to messages. The code sample demonstrates how to send a message and then add a 'like' reaction to that message.

const StreamChat = require('stream-chat').StreamChat;
const client = new StreamChat('api_key');

async function addReaction() {
  const channel = client.channel('messaging', 'general');
  await channel.create();
  const message = await channel.sendMessage({
    text: 'Hello, world!',
    user_id: 'user123',
  });
  await channel.sendReaction(message.id, {
    type: 'like',
    user_id: 'user123',
  });
}
addReaction();

Other packages similar to stream-chat

socket.io

Socket.IO is a library that enables real-time, bidirectional and event-based communication between web clients and servers. While it is more general-purpose and can be used for various real-time applications, it requires more manual setup for chat-specific features compared to stream-chat.

pusher-js

Pusher is a service that provides APIs for building real-time web and mobile applications. Pusher Channels specifically can be used for real-time messaging, but it lacks some of the higher-level abstractions and features specifically tailored for chat applications that stream-chat offers.

firebase

Firebase is a platform developed by Google for creating mobile and web applications. Firebase Realtime Database and Firestore can be used to build real-time chat applications. However, Firebase is a more general-purpose backend-as-a-service and may require more custom development to achieve the same level of chat-specific functionality provided by stream-chat.

README

Official JavaScript SDK for Stream Chat

Official JavaScript API client for Stream Chat, a service for building chat applications.
Explore the docs »

Report Bug · Request Feature

📝 About Stream

You can sign up for a Stream account at our Get Started page.

This library can be used by both frontend and backend applications. For frontend, we have frameworks that are based on this library such as the Flutter, React and Angular SDKs. For more information, check out our docs.

⚙️ Installation

NPM

npm install stream-chat

Yarn

yarn add stream-chat

JS deliver

<script src="https://cdn.jsdelivr.net/npm/stream-chat"></script>

✨ Getting started

The StreamChat client is setup to allow extension of the base types through use of generics when instantiated. The default instantiation has all generics set to Record<string, unknown>.

import { StreamChat } from 'stream-chat';
// Or if you are on commonjs
const StreamChat = require('stream-chat').StreamChat;

const client = StreamChat.getInstance('YOUR_API_KEY', 'API_KEY_SECRET');

const channel = client.channel('messaging', 'TestChannel');
await channel.create();

Or you can customize the generics:

type ChatChannel = { image: string; category?: string };
type ChatUser1 = { nickname: string; age: number; admin?: boolean };
type ChatUser2 = { nickname: string; avatar?: string };
type UserMessage = { country?: string };
type AdminMessage = { priorityLevel: number };
type ChatAttachment = { originalURL?: string };
type CustomReaction = { size?: number };
type ChatEvent = { quitChannel?: boolean };
type CustomCommands = 'giphy';

type StreamType = {
  attachmentType: ChatAttachment;
  channelType: ChatChannel;
  commandType: CustomCommands;
  eventType: ChatEvent;
  messageType: UserMessage | AdminMessage;
  reactionType: CustomReaction;
  userType: ChatUser1 | ChatUser2;
};

const client = StreamChat.getInstance<StreamType>('YOUR_API_KEY', 'API_KEY_SECRET');

// Create channel
const channel = client.channel('messaging', 'TestChannel');
await channel.create();

// Create user
await client.upsertUser({
  id: 'vishal-1',
  name: 'Vishal',
});

// Send message
const { message } = await channel.sendMessage({ text: `Test message` });

// Send reaction
await channel.sendReaction(message.id, { type: 'love', user: { id: 'vishal-1' } });

Custom types provided when initializing the client will carry through to all client returns and provide intellisense to queries.

🔗 (Optional) Development Setup in Combination with our SDKs

Connect to Stream Chat React Native SDK

Run in the root of this repo

yarn link

Run in the root of one of the example apps (SampleApp/TypeScriptMessaging) in the stream-chat-react-native repo

yarn link stream-chat
yarn start

Open metro.config.js file and set value for watchFolders as

const streamChatRoot = '{{CHANGE_TO_THE_PATH_TO_YOUR_PROJECT}}/stream-chat-js'

module.exports = {
  // the rest of the metro config goes here
  ...
  watchFolders: [projectRoot].concat(alternateRoots).concat([streamChatRoot]),
  resolver: {
    // the other resolver configurations go here
    ...
    extraNodeModules: {
      // the other extra node modules go here
      ...
      'stream-chat': streamChatRoot
    }
  }
};

Make sure to replace {{CHANGE_TO_THE_PATH_TO_YOUR_PROJECT}} with the correct path for the stream-chat-js folder as per your directory structure.

Run in the root of this repo

yarn start

📚 More code examples

Head over to docs/typescript.md for more examples.

✍️ Contributing

We welcome code changes that improve this library or fix a problem, please make sure to follow all best practices and add tests if applicable before submitting a Pull Request on Github. We are very happy to merge your code in the official repository. Make sure to sign our Contributor License Agreement (CLA) first. See our license file for more details.

Head over to CONTRIBUTING.md for some development tips.

🧑‍💻 We are hiring!

We've recently closed a $38 million Series B funding round and we keep actively growing. Our APIs are used by more than a billion end-users, and you'll have a chance to make a huge impact on the product within a team of the strongest engineers all over the world.

Check out our current openings and apply via Stream's website.

Changelog

8.44.0 (2024-11-13)

Features

• add typescript support for custom channel member fields (#1389) (f2268df)

Bug Fixes

• thread manager bugs (#1372) (7435a58)