Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Chat
✓ import { Chat } from 'stream-chat-react';
✗ const Chat = require('stream-chat-react').Chat;
Primary wrapper component, providing context for the chat client. Use named import.
Channel
✓ import { Channel } from 'stream-chat-react';
✗ import Channel from 'stream-chat-react/Channel';
Provides context for a specific channel. Use named import.
MessageList
✓ import { MessageList } from 'stream-chat-react';
Component to display messages within a channel. Use named import.
MessageInput
✓ import { MessageInput } from 'stream-chat-react';
Component for typing and sending messages. Use named import.
StreamChat (client)
✓ import { StreamChat } from 'stream-chat';
✗ import { StreamChat } from 'stream-chat-react';
The core chat client class is imported from the separate `stream-chat` package, not `stream-chat-react`.
CSS Styles
✓ import 'stream-chat-react/dist/css/index.css';
✗ import 'stream-chat-react/dist/css/v2/index.css';
As of v14.0.0-beta.4, the CSS import path changed. Ensure you're importing from `dist/css/index.css`.
This quickstart demonstrates how to set up the Stream Chat client, connect a user, join a channel, and render a basic chat UI with message list and input components using `stream-chat-react` v14.
import React, { useEffect, useState } from 'react';
import { StreamChat } from 'stream-chat';
import { Chat, Channel, ChannelHeader, MessageList, MessageInput, Window, LoadingIndicator } from 'stream-chat-react';
import 'stream-chat-react/dist/css/index.css';
const API_KEY = process.env.STREAM_API_KEY ?? '';
const USER_ID = process.env.STREAM_USER_ID ?? 'john-doe';
const USER_TOKEN = process.env.STREAM_USER_TOKEN ?? 'YOUR_USER_TOKEN'; // Generate this on your backend
const client = StreamChat.getInstance(API_KEY);
function App() {
const [channel, setChannel] = useState(null);
useEffect(() => {
async function initChat() {
if (!API_KEY || !USER_ID || !USER_TOKEN) {
console.error('Please provide STREAM_API_KEY, STREAM_USER_ID, and STREAM_USER_TOKEN environment variables.');
return;
}
try {
await client.connectUser(
{
id: USER_ID,
name: USER_ID,
image: `https://getstream.io/random_png/?id=${USER_ID}&name=${USER_ID}`,
},
USER_TOKEN,
);
const newChannel = client.channel('messaging', 'react-chat-demo', {
name: 'React Chat Tutorial',
members: [USER_ID, 'other-user-id'], // Add other users you want in the channel
});
await newChannel.watch();
setChannel(newChannel);
} catch (error) {
console.error('Failed to connect or join channel:', error);
}
}
initChat();
return () => {
client.disconnectUser();
};
}, []);
if (!channel) return <LoadingIndicator />;
return (
<Chat client={client} theme='messaging light'>
<Channel channel={channel}>
<Window>
<ChannelHeader />
<MessageList />
<MessageInput />
</Window>
</Channel>
</Chat>
);
}
export default App;
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'connectUser') OR client.connectUser is not a function
The `StreamChat` client instance from `stream-chat` has not been correctly initialized or passed to the `Chat` component.
fixEnsure `StreamChat.getInstance(API_KEY)` is called and the resulting client object is passed as the `client` prop to the top-level `<Chat>` component.
Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.
Incorrect import of `stream-chat-react` components, typically mixing default and named imports or using CommonJS `require()` in an ESM context.
fixVerify that all `stream-chat-react` components are imported using named imports (e.g., `import { Chat, Channel } from 'stream-chat-react';`). Failed to compile. Module not found: Error: Can't resolve 'stream-chat-react/dist/css/v2/index.css'
This error occurs after upgrading to `stream-chat-react` v14.0.0-beta.4 or higher, where the CSS import path was changed.
fixUpdate the CSS import statement to `import 'stream-chat-react/dist/css/index.css';`.
React Hook "useState" cannot be called inside a callback. React Hooks must be called in a React function component or at the top level of a custom React Hook.
Using React Hooks (like `useState`, `useEffect`) within class components or outside of a functional component's top level, often seen during migration or incorrect component structure.
fixEnsure all React Hooks are called within functional components or custom hooks and follow the Rules of Hooks.
Audit
Dependencies
@breezystack/lamejsrequiredUsed for audio processing, likely for voice messages.
@emoji-mart/datarequiredEmoji data for the emoji picker component.
@emoji-mart/reactrequiredReact components for the emoji picker.
emoji-martrequiredLegacy emoji picker, potentially for backward compatibility or specific features.
reactrequiredCore React library.
react-domrequiredReact DOM rendering library.
stream-chatrequiredThe underlying JavaScript client for interacting with the Stream Chat API.