# Installation

We recommend installing the component library via a package manager.
Stream Chat React is built on top of Stream's [JavaScript Client](/chat/docs/javascript/).

### Install with npm

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

### Install with Yarn

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

Import the default stylesheet once in your app:

```ts
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.

## 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, 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";
```

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 & 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 & 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, 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](/chat/docs/sdk/react/v13/theming/themingv2#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.                             |


---

This page was last updated at 2026-04-21T07:55:46.848Z.

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