feat!: new addon architecture

[kettanaito]

Motivation

Rewrites the addon to be compatible and adhere to the best practices of Storybook addons.

Issues

• Fixes Missing WebSocketHandler type in initialize 2nd parameter #181 (you can provide any handlers you want)
• Fixes FR: Make MSW quite in vitest #174
• Fixes [Storybook 9] Addon compatibility #170
• Closes refactor: change MswParameters and Context from type to interface in decorator.ts #168
• Fixes .play() function not defined when using msw loader #166 (irrelevant)
• Closes Update README.md to add note about handler inheritance #158
• Closes getWorker() TS issue #65 (irrelevant)
• Closes Allow parameters.msw to be a function that takes args #67 (out of scope)

Changes

• Changes LICENSE.md. I'm implementing the new architecture from scratch and listing myself as the author, respectively. The old addon versions retain the old license with all the appropriate attributions.

Architecture

The addon is now used by importing the enableMocking function and calling it in your Storybook's addons array:

// .storybook/preview.ts
import { definePreview } from '@storybook/react-vite'
import { enableMocking } from '@msw/storybook'
import { http, HttpResponse } from 'msw'

export default definePreview({
  //       👇 Register the addon.
  addons: [enableMocking()],
  //           👇 Type-safe `msw` key.
  beforeEach({ msw }) {
    // 👇 Provide global handlers, if you want.
    msw.use(
      http.get('https://api.example.com/user', () => {
        return HttpResponse.json({ name: 'John Maverick' })
      }),
    )
  },
})

That's it. No need to initialize anything or manage worker/server instances. Everything is provisioned automatically for you with optimal defaults.

You can customize the MSW API created via enableMocking by providing it a custom setup function that returns any setup* instance:

enableMocking(async () => {
  const { setupWorker } = await import('msw/browser')
  const worker = setupWorker()
  await worker.start(CUSTOM_OPTIONS)
  return worker
})

Per-story handlers

You can add request handlers for individual stories:

// stories/homepage.stories.tsx
export const HomepageStory: Story = {
  beforeEach({ msw }) {
    msw.use(
      http.get('https://api.example.com/user', () => {
        return HttpResponse.json({ name: 'Alice Sunwell' })
      }),
    )
  },

Internal

• Simplifies the repository structure. Drop the monorepo. Drop the docs and its deployment.
• Migrates to modern tooling (pnpm, tsdown, Vitest).
• Adds meaningful tests:
  • Stories tests that run on a controlled Storybook setup;
  • Play function tests via stories + Vitest.

Todos

• Document the usage (README.md).
• Add type testing to make sure using the addon extends global Storybook types correctly.
• Set storybook.icon.
  • Deploy a *.png logo to MSW website, use that URL as the value.
• Set the correct version in package.json so this releases properly.
• Adds a release job. Run pnpm lint before publishing.
  • Align on the release model with @yannbf
• Add a story test that provides a custom setup function to enableMocking in .storybook/preview.ts.
• Drop support for Node.js.
• Export addon function as default.
• Support CSF 3 (/preview).
• Consider a function to merge handlers from parameters.msw for easier migration.

Questions

• Do we even need the support for msw/node? Both Storybook and its play functions run in the browser (via VBM).

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
msw-storybook-addon	Error		Apr 8, 2026 5:21pm

[yannbf]

Great stuff @kettanaito!! I think we can/should drop support for node. This is definitely a breaking change for users who use the portable stories concept with Jest or Vitest sans-browser mode, but honestly the amount of affected users will be small in comparison to the ones that adopted new testing capabilities of Storybook + Vitest browser mode.

It would be amazing to have https://github.com/stackblitz-labs/pkg.pr.new set up for canary releases.

I'm overall quite excited to see this getting released, and I love to see msw being part of a story context so it's super easy for people to use it! We need to make sure types work well.

Let's chat in detail next week!

[kettanaito]

Thanks for a quick review, @yannbf!

This is going to be a breaking change regardless so it's a great time to drop msw/node if it's no longer needed.

I will configure pkg-pr in a follow-up, let's keep this branch focused on the public APIs and tests.

[binarykitchen]

That's a great PR.

My public library is broken on Storybook level because of this error

Cannot set properties of undefined (setting 'activationPromise')

Source:
https://github.com/binarykitchen/videomail-client/blob/master/.storybook/preview.ts

(AI suggested a workaround I'm not happy with but have put in a separate branch https://github.com/binarykitchen/videomail-client/blob/storybook-preview-fix/.storybook/preview.ts)

[kettanaito]

@binarykitchen, have you tried this branch? There's no more activationPromise involved so your issue seems to be related to the current version of the add-on. In that case, consult the readme and see what you are missing.

[binarykitchen]

Happy to try. But can you please define "this branch" first? Your draft PR or the master branch of this package? Also, I do not see anything about `activationPromise` in any documentation nor changelog. It looks like an undocumented, breaking change to me ...

On 07/04/2026 20:36, Artem Zakharchenko wrote: *kettanaito* left a comment (mswjs/msw-storybook-addon#182) <#182 (comment)> @binarykitchen <https://github.com/binarykitchen>, have you tried this branch? There's no more |activationPromise| involved so your issue seems to be related to the current version of the add-on. In that case, consult the readme and see what you are missing. — Reply to this email directly, view it on GitHub <#182 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABLL2L5JGNAG3AESDLWHU34US4YHAVCNFSM6AAAAACXKYGXBWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DCOJXGY2TGNJVHE>. You are receiving this because you were mentioned.Message ID: ***@***.***>

-- Binary Kitchen Michael Heuberger (Human Being) 1/33 Parrish Road Sandringham Auckland 1025 (New Zealand) Mobile (text only) ... +64 21 261 89 81 Email ................***@***.*** Website ..............https://binarykitchen.com

[kettanaito]

@binarykitchen, I see what's happening. msw@2.13.0 has propagated to you as a part of the install and it broke the internals of the current version of the addon (#183). I was confused about your comment being on a WIP pull request that has nothing to do with either of those things.

Please follow #183 for updates on the issue. I will look into it once I have a moment. For now, you can pin msw to 2.12.x.

[binarykitchen]

Apologies for posting here @kettanaito - all clear now, thanks

[shilman]

This is awesome & very clean!!! Love the new version. Small comments below.

Would love to see a way for existing users to migrate cleanly to the new version, whether it's a codemod, prompt, or a backwards compatibility code snippet that they can paste into their .storybook/preview.ts file