# Installation

> **Info:** This is release candidate documentation for **Stream Chat React SDK v15**. For the latest stable version, see the [latest version (v14)](https://getstream.io/chat/docs/sdk/react/).

Install two packages: `stream-chat`, the [JavaScript client](https://getstream.io/chat/docs/javascript/) that holds the state, and `stream-chat-react`, the components. `stream-chat-react` 15 and `stream-chat` 10 are release candidates, both published under the `rc` tag. `stream-chat-react` 15 needs `stream-chat` 10.0.0-rc.20 or later, and React 17, 18 or 19.

## Install with npm

```bash
npm install stream-chat@rc stream-chat-react@rc
```

## Install with Yarn

```bash
yarn add stream-chat@rc stream-chat-react@rc
```

Import the default stylesheet once in your app:

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

Some optional parts of the SDK have their own entry point and stylesheet. See [Entry points and CSS files](#entry-points-and-css-files) below. To build a first app, continue with the [Quick start](https://getstream.io/chat/docs/sdk/react/v15/getting-started/quick-start/).

## 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.
- Import stylesheets from `stream-chat-react/dist/css/`.
- 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.

>
> **Note:** Upgrade `stream-chat` and `stream-chat-react` together. The React SDK depends on newer low-level client features, so mismatched versions can fail at runtime even if installation succeeds.
>

## Bundle size

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

1. Use named ESM imports

```ts
// ✅ correct
import { Chat, Channel, MessageList, MessageComposer } 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";

// ❌ Not exported: deep `dist/` paths. Import from an entry point instead.
import * as SCR from "stream-chat-react/dist/components/Avatar/Avatar";
```

2. Don’t use CJS (`require()`) in client code when ESM is available.

3. 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 and build   |                                                                               [https://vitejs.dev/guide/build.html](https://vitejs.dev/guide/build.html), [https://rollupjs.org/introduction/#tree-shaking](https://rollupjs.org/introduction/#tree-shaking)                                                                               |
| Webpack tree-shaking and code splitting |                                                                         [https://webpack.js.org/guides/tree-shaking/](https://webpack.js.org/guides/tree-shaking/), [https://webpack.js.org/guides/code-splitting/](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/api-reference/turbopack#bundle-sizes), [https://nextjs.org/docs/app/getting-started/server-and-client-components#reducing-js-bundle-size](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](https://esbuild.github.io/api/#tree-shaking)                                                                                                                         |
|     General: what is tree-shaking?      |                                                                                                            [https://developer.mozilla.org/docs/Glossary/Tree_shaking](https://developer.mozilla.org/docs/Glossary/Tree_shaking)                                                                                                            |
|  React: code splitting with React.lazy  |                                                                                                                              [https://react.dev/reference/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](https://rollupjs.org/introduction/#visualizer)                                    |
|     Webpack bundle analyzer      |                       [https://github.com/webpack-contrib/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](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. Switch to named imports from the entry points 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](https://getstream.io/chat/docs/sdk/react/v15/ui/customizing/theming/#importing-the-stylesheet) 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.                                |

## Entry points and CSS files

The SDK has one main entry point and six optional ones. An optional part is its own entry point, so an app that never imports it doesn't bundle it. A part with its own styles has its own stylesheet, imported after `index.css`.

| Part                                                         | Import from                        | Stylesheet              |
| ------------------------------------------------------------ | ---------------------------------- | ----------------------- |
| Components, contexts and hooks                               | `stream-chat-react`                | `index.css`             |
| Layout: `ChatView` and its slots                             | `stream-chat-react/slot-layout`    | included in `index.css` |
| Slot geometry: which layout slots are collapsed or covered   | `stream-chat-react/slot-geometry`  | none                    |
| Channel details: members, media, files and pinned messages   | `stream-chat-react/channel-detail` | `channel-detail.css`    |
| Emoji picker and emoji suggestions in the composer           | `stream-chat-react/emojis`         | `emoji-picker.css`      |
| MP3 encoding for voice recordings                            | `stream-chat-react/mp3-encoder`    | none                    |
| AI components: streaming messages, Markdown, the AI composer | `stream-chat-react/ai-components`  | `ai-components.css`     |

Every stylesheet is in `stream-chat-react/dist/css/`. For example, an app that uses channel details and the emoji picker imports:

```ts
import "stream-chat-react/dist/css/index.css";
import "stream-chat-react/dist/css/channel-detail.css";
import "stream-chat-react/dist/css/emoji-picker.css";
```

Two entry points need packages that you install yourself, only if you use them:

- `stream-chat-react/emojis` needs `emoji-mart` and `@emoji-mart/data`.
- `stream-chat-react/mp3-encoder` needs `@breezystack/lamejs`.

One more stylesheet, `emoji-replacement.css`, loads a color font for country flag emoji, which Windows shows as letters. Import it and set `useImageFlagEmojisOnWindows` on `Chat`. The class it needs is added to each `Channel` and to `ChannelNavigation`'s root, so the font applies inside them.

Each entry point's exports are listed in [Entry points and CSS files](https://getstream.io/chat/docs/sdk/react/v15/reference/entry-points-and-css-files/).

To load the stylesheets into a CSS cascade layer, so your own rules win without `!important`, see [Theming](https://getstream.io/chat/docs/sdk/react/v15/ui/customizing/theming/#css-layers).

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react/v15/getting-started/installation/](https://getstream.io/chat/docs/sdk/react/v15/getting-started/installation/).