# msw-storybook-addon

> Mock APIs in Storybook using Mock Service Worker.

Latest version **3.0.3** (published 2026-09-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install msw-storybook-addon
pnpm add msw-storybook-addon
yarn add msw-storybook-addon
bun add msw-storybook-addon
```

Provides the command `msw-storybook-addon`.

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 3.0.3 |
| Published | 2026-09-15 |
| First published | 2020-12-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 0 |
| Unpacked size | 57.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 495 |
| Author | Artem Zakharchenko <kettanaito@gmail.com> |
| Maintainers | itaditya, kettanaito, yannbf |
| Keywords | storybook-addon, api, mock, http, graphql, websocket, sse, network, request, intercept |

## Links

- npm: https://www.npmjs.com/package/msw-storybook-addon
- Repository: https://github.com/mswjs/msw-storybook-addon
- Issues: https://github.com/mswjs/msw-storybook-addon/issues
- npm.io page: https://npm.io/package/msw-storybook-addon

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 3.0.3 (latest) — 2026-09-15
- 2.0.4--canary.165.3d455a6.0 (canary) — 2024-11-05
- 2.0.0-beta.2 (beta) — 2024-03-28
- 2.0.0-next.1 (next) — 2023-05-14
- 3.0.2 — 2026-09-15
- 3.0.1 — 2026-09-15
- 3.0.0 — 2026-07-24
- 2.0.7 — 2026-04-08
- 2.0.6 — 2025-10-10
- 2.0.5 — 2025-06-05
- 2.0.4 — 2024-11-05
- 2.0.3 — 2024-07-12
- 2.0.3--canary.157.8ab54e9.0 — 2024-07-12
- 2.0.3--canary.94c4324.0 — 2024-07-12
- 2.0.3--canary.cc5613e.0 — 2024-07-12
- … 61 more at https://npm.io/package/msw-storybook-addon/versions

## README

# MSW Storybook Addon

Mock API requests in Storybook with Mock Service Worker.

## Usage

### Install

```sh
npm i msw-storybook-addon -D
```

> Make sure you have `msw@2.x` installed as a peer dependency.

### Generate the worker script

Next, use the MSW CLI to generate a worker script at the given path:

```sh
npx msw init ./public --save
```

> Replace `./public` with the path to your static directory of Storybook.

### Configure Storybook

#### CSF 3.0

> The loader API for CSF 3.0 is _deprecated_. Please consider using the [CSF Next](#csf-next) API instead.

```ts
// .storybook/main.ts
export default {
  addons: ['msw-storybook-addon'],
}
```

```ts
// .storybook/preview.ts
import { mswLoader } from 'msw-storybook-addon/csf3'

export default {
  loaders: [mswLoader()],
  parameters: {
    msw: [...initialHandlers]
  }
}
```

#### CSF Next

If you are using the [CSF Next](https://storybook.js.org/docs/api/csf/csf-next) syntax (also known as CSF Factories), it's enough to import and call the addon function in `preview.ts`:

```ts
// .storybook/preview.ts
import addonMsw from 'msw-storybook-addon'

export default definePreview({
  addons: [addonMsw()],
})
```

> `parameters.msw` is not supported in CSF Next. It is preserved only for CSF 3.0 to make migration easier — use the `beforeEach` hook instead.

#### Types

The addon types `context.msw` (and, for CSF 3.0, `parameters.msw`) through module augmentation. That augmentation ships with every entrypoint of the addon, so it is applied to any TypeScript program that imports the addon.

**CSF Next**: nothing to do. Your stories import `preview`, and `preview` imports the addon, so the types reach every story automatically.

**CSF 3.0**, or any setup where the stories are compiled without `.storybook/preview.ts` (e.g. a `tsconfig.json` whose `include` doesn't cover the `.storybook` directory): reference the types explicitly in your `tsconfig.json`:

```json
{
  "compilerOptions": {
    "types": ["msw-storybook-addon/types"]
  }
}
```

> In CSF 3.0, reference `msw-storybook-addon/csf3` instead — it types `parameters.msw` as well.

#### Custom worker setup

By default, the addon creates and starts the worker for you: it starts quietly and ignores common asset and Storybook-internal requests. To customize that behavior (e.g. `worker.start()` options or initial handlers), provide a setup function that creates the worker, starts it, and returns it.

In CSF 3.0, pass it to `mswLoader`:

```ts
// .storybook/preview.ts
import { setupWorker } from 'msw/browser'
import { mswLoader } from 'msw-storybook-addon/csf3'

export default {
  loaders: [
    mswLoader(async () => {
      const worker = setupWorker()
      await worker.start({ onUnhandledRequest: 'bypass' })
      return worker
    })
  ]
}
```

In CSF Next, pass it to `addonMsw`:

```ts
// .storybook/preview.ts
import { setupWorker } from 'msw/browser'
import addonMsw from 'msw-storybook-addon'

export default definePreview({
  addons: [
    addonMsw(async () => {
      const worker = setupWorker()
      await worker.start({ onUnhandledRequest: 'bypass' })
      return worker
    })
  ],
})
```

> Handlers passed to `setupWorker()` act as initial handlers and survive the automatic handler reset between stories.

### Provide handlers

If you have correctly installed and configured this addon, it will extend your story context with the `msw` property. Use that reference to control API mocking in your stories, e.g. by adding request handler overrides via `msw.use()`.

#### Global handlers

Provide request handlers in `preview.ts` to define the network behaviors that affect all your stories.

```ts
// .storybook/preview.ts
import { http, HttpResponse } from 'msw'

export default {
  beforeEach({ msw }) {
    msw.use(
      http.get('https://api.acme.com/user', () => {
        return HttpResponse.json({ name: 'John Maverick' })
      }),
    )
  },
}
```

#### Story handlers

To describe network behaviors on a story basis, add them in the `beforeEach` hook of the respective story.

```ts
export const UserProfileNetworkError: Story = {
  beforeEach({ msw }) {
    msw.use(
      http.get('https://api.acme.com/user', () => {
        return HttpResponse.error()
      }),
    )
  },
}
```

## Related materials

- [Mock Service Worker](https://mswjs.io/docs)

---
_Source: https://npm.io/package/msw-storybook-addon · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._