Installation

We recommend installing the component library via a package manager. Stream Chat React is built on top of Stream's JavaScript Client.

Install with npm

npm install stream-chat stream-chat-react

Install with Yarn

yarn add stream-chat stream-chat-react

Import the default stylesheet once in your app:

import "stream-chat-react/dist/css/v2/index.css";

With installation out of the way, let’s get started.

Best Practices

Install both stream-chat and stream-chat-react to keep client and UI versions aligned.
Import the default stylesheet once at app entry to avoid duplicate CSS and overrides.
Prefer ESM named imports from stream-chat-react to enable tree-shaking.
Keep bundler config stock first; only add customizations if bundle size or SSR needs demand it.
Verify the build pipeline handles CSS imports in your target framework before shipping.

The SDK is optimized for tree-shaking. Bundlers like Vite/Rollup, Webpack, and esbuild can remove unused components, so your final size depends on what you actually render (not the total package size reported by Bundlephobia).

Best practices for optimal bundle size

Besides minifying and gzipping your app, here’s how to keep stream-chat-react as small as possible.

Imports that support tree-shaking

Use named ESM imports

// ✅ correct
import { Chat, Channel, MessageList, MessageInput } from "stream-chat-react";

// ❌ Avoid (harder to tree-shake)
import * as SCR from "stream-chat-react";

// ❌ Avoid re-export from your own index file
export * from "stream-chat-react";

// ❌ Avoid deep `dist/` paths in web code or require()
import * as SCR from "stream-chat-react/dist/components/Avatar/Avatar";

Don’t use CJS (require()) in client code when ESM is available.
Only import what you render - if you don’t show a component, don’t import it so that your bundler can drop it.

Tree-shaking works with stream-chat-react because it ships ESM builds with granular exports. Use named imports and lazy-load optional features so bundlers can drop unused code.

Bundler docs

Modern bundlers document tree-shaking and code-splitting; here are some starting points:

Framework	Links
Vite (Rollup) Tree-shaking & Build	https://vitejs.dev/guide/build.html, https://rollupjs.org/introduction/#tree-shaking
Webpack Tree-shaking & Code Splitting	https://webpack.js.org/guides/tree-shaking/, https://webpack.js.org/guides/code-splitting/
Next.js Dynamic Imports	https://nextjs.org/docs/app/api-reference/turbopack#bundle-sizes, https://nextjs.org/docs/app/getting-started/server-and-client-components#reducing-js-bundle-size
esbuild Tree-shaking	https://esbuild.github.io/api/#tree-shaking
General: What is tree-shaking?	https://developer.mozilla.org/docs/Glossary/Tree_shaking
React: Code-splitting with React.lazy	https://react.dev/reference/react/lazy

Bundle size measurement

Bundle size analyzers by framework:

Framework	Links
Vite / Rollup: Bundle Visualizer	https://rollupjs.org/introduction/#visualizer
Webpack Bundle Analyzer	https://github.com/webpack-contrib/webpack-bundle-analyzer
Next.js: Next Bundle Analyzer	https://nextjs.org/docs/app/guides/package-bundling#analyzing-javascript-bundles

Common gotchas (and easy fixes)

Question	Answer
“My bundle didn’t shrink.”	Usually caused by namespace imports, or deep dist/ imports. Switch to named imports from the root and rebuild.
“I removed a component, but it’s still in the bundle.”	Something re-exports it or you import it indirectly. Import only exactly what you render, directly from stream-chat-react.
“Styles disappeared.”	Don’t mark CSS as tree-shakable. Check how to import styles for stream-chat-react correctly.
“Gallery/emoji added lots of KB.”	Lazy-load those modules. Many libraries ship large data (sprites, emoji sheets). Load them only when needed.

Overview

Getting Started