or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdinitialization.mdstorybook-integration.mdworker-management.md
tile.json

tessl/npm-msw-storybook-addon

Mock API requests in Storybook with Mock Service Worker.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/msw-storybook-addon@2.0.x

To install, run

npx @tessl/cli install tessl/npm-msw-storybook-addon@2.0.0

index.mddocs/

MSW Storybook Addon

MSW Storybook Addon enables developers to mock API requests directly within Storybook stories using Mock Service Worker (MSW). It provides seamless integration of network request mocking in component documentation and testing environments, supporting REST and GraphQL API mocking across browser, Node.js, and React Native platforms.

Package Information

  • Package Name: msw-storybook-addon
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install msw msw-storybook-addon --save-dev

Core Imports

import { initialize, mswLoader, getWorker, waitForMswReady } from "msw-storybook-addon";

For CommonJS:

const { initialize, mswLoader, getWorker, waitForMswReady } = require("msw-storybook-addon");

Basic Usage

// In .storybook/preview.ts
import { initialize, mswLoader } from "msw-storybook-addon";
import { http, HttpResponse } from "msw";

// Initialize MSW
initialize();

// Configure loaders
export const loaders = [mswLoader];

// In your story file
import type { Meta, StoryObj } from "@storybook/react";
import { http, HttpResponse } from "msw";
import { UserProfile } from "./UserProfile";

const meta: Meta<typeof UserProfile> = {
  title: "Example/UserProfile",
  component: UserProfile,
};

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

export const Success: Story = {
  parameters: {
    msw: {
      handlers: [
        http.get("/api/user", () => {
          return HttpResponse.json({
            name: "John Doe",
            email: "john@example.com",
          });
        }),
      ],
    },
  },
};

Architecture

MSW Storybook Addon is built around several key components:

  • Platform-Specific Initialization: Separate implementations for browser (service worker), Node.js (server), and React Native (native server)
  • Storybook Integration: Loaders and decorators that apply MSW handlers per story
  • Handler Management: Automatic request handler registration and cleanup
  • Type Safety: Full TypeScript support with MSW integration

Capabilities

MSW Initialization

Core MSW initialization functionality that sets up Mock Service Worker for the appropriate platform (browser, Node.js, or React Native).

function initialize(
  options?: InitializeOptions,
  initialHandlers?: RequestHandler[]
): SetupWorker | SetupServer;

function waitForMswReady(): Promise<void>;

type InitializeOptions = 
  | Parameters<SetupWorker['start']>[0]  // Browser
  | Parameters<SetupServer['listen']>[0]; // Node.js/React Native

MSW Initialization

Storybook Integration

Storybook loaders and decorators for applying MSW handlers on a per-story basis, with automatic cleanup and error handling.

function mswLoader(context: Context): Promise<{}>;

interface Context {
  parameters: MswParameters;
}

interface MswParameters {
  [key: string]: any;
  msw?: RequestHandler[] | {
    handlers: RequestHandler[] | Record<string, RequestHandler | RequestHandler[]>;
  };
}

Storybook Integration

Worker Management

Functions for managing the MSW worker/server instance, including access and direct manipulation.

function getWorker(): SetupWorker | SetupServer;

Worker Management

Types

// MSW types imported from 'msw'
import type { RequestHandler } from 'msw';
import type { SetupWorker } from 'msw/browser';
import type { SetupServer } from 'msw/node';

interface MswParameters {
  [key: string]: any;
  msw?: RequestHandler[] | {
    handlers: RequestHandler[] | Record<string, RequestHandler | RequestHandler[]>;
  };
}

interface Context {
  parameters: MswParameters;
}

type InitializeOptions = 
  | Parameters<SetupWorker['start']>[0]  // Browser platform
  | Parameters<SetupServer['listen']>[0]; // Node.js/React Native platforms