msw-storybook-addon

Most migration tasks when upgrading from version 2.x.x to 3.x.x can be automated. Run the following command to rewrite your preview and main configurations and migrate parameters.msw to beforeEach in your stories. Any manual migrations required will be listed in the output.

npx msw-storybook-addon-migrate

Install the addon as a development dependency using npm. Ensure you have msw@2.x installed as a peer dependency.

npm i msw-storybook-addon -D

In version 3.x.x, the initialize function has been removed. The addon now manages the worker lifecycle automatically. If you previously used initialize to pass custom options (like onUnhandledRequest) or initial handlers, you must now pass a custom setup function to mswLoader. This setup function is responsible for creating and starting the worker.

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

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

export default preview

In version 3.x.x, parameters.msw is deprecated in favor of using the beforeEach hook. The addon now provides an msw property within the story context. Using beforeEach is the recommended way to add request handlers globally in preview.ts or on a per-story basis. Handlers are automatically reset between stories.

// ❌ Deprecated: defining handlers in parameters
export const MyStory = {
  parameters: {
    msw: {
      handlers: [...] 
    }
  }
}

// ✅ Recommended: using the beforeEach hook
export const MyStory = {
  beforeEach({ msw }) {
    msw.use(...)
  }
}

Use the MSW CLI to generate a worker script in your Storybook static directory. Replace ./public with the actual path to your Storybook static directory.

npx msw init ./public --save

For CSF Next (CSF Factories), simply import and call the addon function within definePreview in your preview.ts file.

Note: parameters.msw is not supported in CSF Next. Instead, use the beforeEach hook to manage handlers.

To enable type safety, add msw-storybook-addon/types to the types array in your tsconfig.json.

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

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

{
  "include": [".storybook/preview.ts", "..."],
  "compilerOptions": {
    "types": ["msw-storybook-addon/types"]
  }
}

The addon extends the story context with an msw property. You can use msw.use() to control API mocking.

Global Handlers

Define network behaviors for all stories in .storybook/preview.ts using the beforeEach hook.

Story-specific Handlers

Define specific network behaviors for a single story by adding a beforeEach hook directly to that story object.

// Global handlers in .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-specific handlers
export const UserProfileNetworkError: Story = {
  beforeEach({ msw }) {
    msw.use(
      http.get('https://api.acme.com/user', () => {
        return HttpResponse.error()
      }),
    )
  },
}

Note: The CSF 3.0 loader API is deprecated. Use the CSF Next API instead if possible.

To use CSF 3.0:

1. Add the addon to .storybook/main.ts.
2. Import and use mswLoader in .storybook/preview.ts.
3. Define initial handlers in parameters.msw.

To enable type safety for parameters.msw, add msw-storybook-addon/csf3 to the types array in your tsconfig.json.

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

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

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

{
  "include": [".storybook/preview.ts", "..."],
  "compilerOptions": {
    "types": ["msw-storybook-addon/csf3"]
  }
}

If you are using CSF Next syntax, you do not need to use mswLoader. Instead, import and call addonMsw directly within the addons array of your definePreview configuration in preview.ts. Note that parameters.msw is not supported in CSF Next; you must use the beforeEach hook to manage handlers.

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

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

To prevent race conditions where stories request data before the service worker is registered, replace mswDecorator with mswLoader. Loaders execute before a story renders, whereas decorators execute during the render process. mswLoader respects the same parameters.msw settings.

// .storybook/preview.js
-import { initialize, mswDecorator } from 'msw-storybook-addon'
+import { initialize, mswLoader } from 'msw-storybook-addon'

initialize()

const preview = {
-  decorators: [mswDecorator]
+  loaders: [mswLoader]
}

export default preview