0
# MSW Storybook Addon
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: msw-storybook-addon
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install msw msw-storybook-addon --save-dev`
10

11
## Core Imports
12

13
```typescript
14
import { initialize, mswLoader, getWorker, waitForMswReady } from "msw-storybook-addon";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { initialize, mswLoader, getWorker, waitForMswReady } = require("msw-storybook-addon");
21
```
22

23
## Basic Usage
24

25
```typescript
26
// In .storybook/preview.ts
27
import { initialize, mswLoader } from "msw-storybook-addon";
28
import { http, HttpResponse } from "msw";
29

30
// Initialize MSW
31
initialize();
32

33
// Configure loaders
34
export const loaders = [mswLoader];
35

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

41
const meta: Meta<typeof UserProfile> = {
42
  title: "Example/UserProfile",
43
  component: UserProfile,
44
};
45

46
export default meta;
47
type Story = StoryObj<typeof meta>;
48

49
export const Success: Story = {
50
  parameters: {
51
    msw: {
52
      handlers: [
53
        http.get("/api/user", () => {
54
          return HttpResponse.json({
55
            name: "John Doe",
56
            email: "john@example.com",
57
          });
58
        }),
59
      ],
60
    },
61
  },
62
};
63
```
64

65
## Architecture
66

67
MSW Storybook Addon is built around several key components:
68

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

74
## Capabilities
75

76
### MSW Initialization
77

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

80
```typescript { .api }
81
function initialize(
82
  options?: InitializeOptions,
83
  initialHandlers?: RequestHandler[]
84
): SetupWorker | SetupServer;
85

86
function waitForMswReady(): Promise<void>;
87

88
type InitializeOptions = 
89
  | Parameters<SetupWorker['start']>[0]  // Browser
90
  | Parameters<SetupServer['listen']>[0]; // Node.js/React Native
91
```
92

93
[MSW Initialization](./initialization.md)
94

95
### Storybook Integration
96

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

99
```typescript { .api }
100
function mswLoader(context: Context): Promise<{}>;
101

102
interface Context {
103
  parameters: MswParameters;
104
}
105

106
interface MswParameters {
107
  [key: string]: any;
108
  msw?: RequestHandler[] | {
109
    handlers: RequestHandler[] | Record<string, RequestHandler | RequestHandler[]>;
110
  };
111
}
112
```
113

114
[Storybook Integration](./storybook-integration.md)
115

116
### Worker Management
117

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

120
```typescript { .api }
121
function getWorker(): SetupWorker | SetupServer;
122
```
123

124
[Worker Management](./worker-management.md)
125

126
## Types
127

128
```typescript { .api }
129
// MSW types imported from 'msw'
130
import type { RequestHandler } from 'msw';
131
import type { SetupWorker } from 'msw/browser';
132
import type { SetupServer } from 'msw/node';
133

134
interface MswParameters {
135
  [key: string]: any;
136
  msw?: RequestHandler[] | {
137
    handlers: RequestHandler[] | Record<string, RequestHandler | RequestHandler[]>;
138
  };
139
}
140

141
interface Context {
142
  parameters: MswParameters;
143
}
144

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