[Bug]: MSW Storybook Addon Fails to Initialize with Lazy Compilation in Rsbuild Storybook

[tmeindle]

Version

## Environment

- **Storybook**: 10.1.10
- **storybook-react-rsbuild**: 3.2.0
- **msw**: 2.12.6
- **msw-storybook-addon**: 2.0.6
- **@storybook/addon-docs**: 10.1.10
- **@storybook/react**: 10.1.10
- **React**: 19.2.3
- **OS**: Windows

Details

Description

When using the MSW Storybook addon with Rsbuild's lazy compilation feature enabled (default?), the addon fails to initialize correctly, causing stories that use MSW handlers to get stuck in an infinite loading state. This issue does not occur when lazy compilation is disabled.

Steps to Reproduce

1. Configure Storybook with Rsbuild and MSW addon:

.storybook/main.ts:

import type { StorybookConfig } from 'storybook-react-rsbuild';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['@storybook/addon-docs', 'storybook-addon-rslib'],
  staticDirs: [resolve(__dirname, '../public')],
  framework: {
    name: 'storybook-react-rsbuild',
    options: {
      builder: {
        lazyCompilation: true,  // This is enabled by default
      },
    },
  },
};

export default config;

.storybook/preview.ts:

import type { Preview } from 'storybook-react-rsbuild';
import { initialize, mswLoader } from 'msw-storybook-addon';

initialize({
  onUnhandledRequest: 'bypass',
});

const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
  loaders: [mswLoader],
};

export default preview;

2. Create a story that uses MSW handlers:

src/UserProfile/UserProfile.stories.tsx:

import type { Meta, StoryObj } from '@storybook/react';
import { http, HttpResponse } from 'msw';
import { UserProfile } from './UserProfile.component';

const meta = {
  title: 'Components/UserProfile',
  component: UserProfile,
  parameters: {
    layout: 'centered',
  },
} satisfies Meta<typeof UserProfile>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Default: Story = {
  args: {
    userId: 1,
  },
  parameters: {
    msw: {
      handlers: [
        http.get('/api/users/1', () => {
          return HttpResponse.json({
            id: 1,
            name: 'John Doe',
            email: 'john.doe@example.com',
            avatar: 'https://i.pravatar.cc/150?img=1',
            role: 'Developer',
          });
        }),
      ],
    },
  },
};

3. Ensure mockServiceWorker.js is in the public directory
4. Run Storybook: pnpm storybook (or npm run storybook)
5. Navigate to a story that uses MSW handlers (e.g., "Components/UserProfile")

Expected Behavior

The story should load normally with MSW handlers intercepting and mocking API requests. The component should render with the mocked data.

Actual Behavior

The story gets stuck in an infinite loading state and never renders. The MSW service worker appears not to initialize or activate properly when lazy compilation is enabled. The browser tab shows a perpetual loading spinner. No errors are reported in the console.

Workaround

Disabling lazy compilation resolves the issue:

.storybook/main.ts:

import type { StorybookConfig } from 'storybook-react-rsbuild';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { mergeRsbuildConfig } from '@rsbuild/core';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['@storybook/addon-docs', 'storybook-addon-rslib'],
  staticDirs: [resolve(__dirname, '../public')],
  framework: {
    name: 'storybook-react-rsbuild',
    options: {
      builder: {
        lazyCompilation: false,  // Disable lazy compilation
      },
    },
  },
  rsbuildFinal: async (config) => {
    return mergeRsbuildConfig(config, {
      dev: {
        lazyCompilation: false,
      },
    });
  },
};

export default config;

With lazy compilation disabled, all MSW-dependent stories load and render correctly.

Additional Context

• This appears to be a timing or initialization issue where lazy compilation interferes with the MSW service worker registration or the mswLoader execution.
• The service worker file (mockServiceWorker.js) is in the public directory and configured via staticDirs.
• The issue may be related to how Rsbuild's lazy compilation defers module loading, potentially causing the MSW initialization to happen before required dependencies are available, or vice versa.
• Stories without MSW handlers work fine with lazy compilation enabled.
• The issue is consistent and reproducible across multiple stories that use MSW.

Impact

This bug prevents using lazy compilation (which significantly improves dev server startup time) in projects that rely on MSW for API mocking in Storybook. This is a significant limitation for larger projects where lazy compilation provides substantial performance benefits.

Reproduce link

n/a attached

Reproduce Steps

see above

repro.zip

[fi3ework]

i attempted to reproduce this error and found that the actual issue differs slightly from your description:

• regardless of whether lazy compilation is enabled, visiting http://localhost:6006/?path=/docs/components-userprofile--docs results in the API being successfully intercepted, as shown here:

  

• however, under the same conditions (visiting the same URL with or without lazy compilation), the API sometimes fails to be intercepted, as shown here:

  

please confirm if these reproduction results match what you are seeing.

[fi3ework]

Investigation Results

After extensive debugging, I've identified that this issue is not caused by storybook-rsbuild or lazy compilation. The root cause is a Storybook core limitation that has existed since 2020.

Root Cause Analysis

The issue occurs specifically in Docs view (viewMode=docs) when using inline story rendering (the default). In this mode, CSF loaders (like mswLoader) are not properly executed for stories.

Technical Details:

In Storybook's core source code (DocsContext.ts, lines 270-276):

getStoryContext = (story: PreparedStory<TRenderer>) => {
  return {
    ...this.store.getStoryContext(story),
    loaded: {},  // ← HARDCODED! Always returns empty object
    viewMode: 'docs',
  };
};

This means:

• Story view: Loaders execute via applyLoaders() → results stored in context.loaded → MSW handlers are applied ✅
• Docs view (inline): DocsContext.getStoryContext() returns loaded: {} → loader results are ignored → MSW handlers never applied ❌

Additional Verification

I tested with @storybook/react-vite builder and confirmed the exact same behavior:

Builder	Story View	Docs View
Rsbuild	✅ MSW works	❌ MSW fails
Vite	✅ MSW works	❌ MSW fails

This proves it's a Storybook core issue, not specific to any builder.

Existing Storybook Issue

This is tracked in Storybook issue #12726: "Addon-docs: Inline rendering support for loaders"

• Status: Still OPEN (since October 2020)

Workaround

Add the following to your .storybook/preview.ts to force iframe rendering in Docs view:

const preview: Preview = {
  parameters: {
    docs: {
      story: {
        inline: false,  // Force iframe rendering - loaders work correctly in iframes
      },
    },
  },
  loaders: [mswLoader],
};

Trade-offs:

• ✅ MSW and all loaders work correctly in Docs view
• ⚠️ Slightly slower rendering (each story loads in separate iframe)
• ⚠️ Stories won't share the same document context

Conclusion

storybook-rsbuild is not the cause of this issue. The framework only handles building Storybook bundles using Rsbuild/Rspack and delegates all rendering to Storybook core's PreviewWeb class.

Recommendations:

1. Use the docs.story.inline: false workaround above
2. Watch/comment on Storybook issue #12726 for a proper fix
3. Re-enable lazy compilation for better dev performance (it's not the actual cause)

[tmeindle]

Sorry I had an extra lazy compilation false in the rslib config..

I have been using rsbuild and rslib for like 2 years now. This was never an issue before the lazy compilation was turned on by default in rslib. Took me a while to figure out it was the lazy compilation and I worked around it by turning off lazy compilation in rslib. Definitely not a core storybook issue. Their default vite builder works flawlessly with the msw addon enabled.

It isn't only docs.. It's all stories I have a video but it won't let me attach it to the post.

You need to remove the lazy compilation in the rslib.config in the root too to see the actual problem.

The problem you are describing is different and adding inline false does not fix the issue.

[tmeindle]

The following video shows
video

1. that when lazy compilation is enabled (default behavior or rslib) stories with MSW loaders do not load and just spin.. Not just the docs page every story.
2. Closing the browser and killing the storybook instance then turning off lazy compilation in the rslib.config and rerunning storybook
3. When the browser opens everything loads perfectly fine

Note: Removing the mdx files from the repro altogether (no docs page) results in same behavior

[fi3ework]

got it, i will continue to investigate the cause.