0
# Worker Management
1

2
Functions for managing the MSW worker/server instance, including access and runtime handler management. These functions provide low-level control over the MSW instance for advanced use cases.
3

4
## Capabilities
5

6
### Get Worker Function
7

8
Returns the currently active MSW worker or server instance for direct manipulation.
9

10
```typescript { .api }
11
/**
12
 * Get the current MSW worker/server instance
13
 * @returns SetupWorker (browser) or SetupServer (Node.js/React Native)
14
 * @throws Error if no worker is initialized
15
 */
16
function getWorker(): SetupWorker | SetupServer;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { initialize, getWorker } from "msw-storybook-addon";
23
import { http, HttpResponse } from "msw";
24

25
// Initialize MSW first
26
initialize();
27

28
// Get the worker instance
29
const worker = getWorker();
30

31
// Add handlers at runtime
32
worker.use(
33
  http.get("/api/dynamic", () => {
34
    return HttpResponse.json({ timestamp: Date.now() });
35
  })
36
);
37

38
// Reset all handlers
39
worker.resetHandlers();
40

41
// Listen to request events (browser only)
42
if ('events' in worker) {
43
  worker.events.on('request:start', ({ request }) => {
44
    console.log('Request started:', request.url);
45
  });
46
}
47
```
48

49
## Worker Instance Methods
50

51
The returned worker instance provides access to MSW's full API:
52

53
### Browser Worker (SetupWorker)
54

55
```typescript { .api }
56
// MSW types imported from 'msw'
57
import type { RequestHandler } from 'msw';
58
import type { SetupWorker } from 'msw/browser';
59
import type { SetupServer } from 'msw/node';
60

61
interface SetupWorker {
62
  /** Add request handlers to the worker */
63
  use(...handlers: RequestHandler[]): void;
64
  
65
  /** Remove specific request handlers */
66
  restoreHandlers(): void;
67
  
68
  /** Reset all request handlers to initial state */
69
  resetHandlers(...handlers: RequestHandler[]): void;
70
  
71
  /** Stop the service worker */
72
  stop(): void;
73
  
74
  /** Event emitter for request lifecycle events */
75
  events: {
76
    on(event: string, listener: Function): void;
77
    off(event: string, listener: Function): void;
78
  };
79
}
80
```
81

82
### Node.js/React Native Server (SetupServer)
83

84
```typescript { .api }
85
interface SetupServer {
86
  /** Add request handlers to the server */
87
  use(...handlers: RequestHandler[]): void;
88
  
89
  /** Remove specific request handlers */
90
  restoreHandlers(): void;
91
  
92
  /** Reset all request handlers to initial state */
93
  resetHandlers(...handlers: RequestHandler[]): void;
94
  
95
  /** Stop the server */
96
  close(): void;
97
  
98
  /** Event emitter for request lifecycle events */
99
  events: {
100
    on(event: string, listener: Function): void;
101
    off(event: string, listener: Function): void;
102
  };
103
}
104
```
105

106
## Runtime Handler Management
107

108
### Adding Handlers Dynamically
109

110
```typescript
111
import { getWorker } from "msw-storybook-addon";
112
import { http, HttpResponse } from "msw";
113

114
const worker = getWorker();
115

116
// Add new handlers
117
worker.use(
118
  http.get("/api/users/:id", ({ params }) => {
119
    return HttpResponse.json({ 
120
      id: params.id, 
121
      name: `User ${params.id}` 
122
    });
123
  }),
124
  http.post("/api/users", async ({ request }) => {
125
    const userData = await request.json();
126
    return HttpResponse.json({ 
127
      id: Math.random().toString(),
128
      ...userData 
129
    });
130
  })
131
);
132
```
133

134
### Resetting Handlers
135

136
```typescript
137
import { getWorker } from "msw-storybook-addon";
138

139
const worker = getWorker();
140

141
// Reset to initial handlers (from initialize())
142
worker.resetHandlers();
143

144
// Reset and add new default handlers
145
worker.resetHandlers(
146
  http.get("/api/default", () => {
147
    return HttpResponse.json({ message: "Default response" });
148
  })
149
);
150
```
151

152
### Restoring Handlers
153

154
```typescript
155
import { getWorker } from "msw-storybook-addon";
156

157
const worker = getWorker();
158

159
// Temporarily override handlers
160
worker.use(
161
  http.get("/api/temp", () => {
162
    return HttpResponse.json({ temp: true });
163
  })
164
);
165

166
// Restore to previous state
167
worker.restoreHandlers();
168
```
169

170
## Event Handling
171

172
### Request Lifecycle Events
173

174
```typescript
175
import { getWorker } from "msw-storybook-addon";
176

177
const worker = getWorker();
178

179
// Listen to request events
180
worker.events.on('request:start', ({ request }) => {
181
  console.log('Request started:', request.method, request.url);
182
});
183

184
worker.events.on('request:match', ({ request, handler }) => {
185
  console.log('Request matched:', request.url, 'by', handler.info.header);
186
});
187

188
worker.events.on('request:unhandled', ({ request }) => {
189
  console.log('Unhandled request:', request.method, request.url);
190
});
191
```
192

193
### Cleanup Event Listeners
194

195
```typescript
196
import { getWorker } from "msw-storybook-addon";
197

198
const worker = getWorker();
199

200
const requestHandler = ({ request }) => {
201
  console.log('Request:', request.url);
202
};
203

204
// Add listener
205
worker.events.on('request:start', requestHandler);
206

207
// Remove listener
208
worker.events.off('request:start', requestHandler);
209
```
210

211
## Error Handling
212

213
### Worker Not Initialized
214

215
If `getWorker()` is called before `initialize()`:
216

217
```typescript
218
try {
219
  const worker = getWorker();
220
} catch (error) {
221
  console.error(error.message);
222
  // "[MSW] Failed to retrieve the worker: no active worker found. Did you forget to call "initialize"?"
223
}
224
```
225

226
### Platform-Specific Errors
227

228
```typescript
229
import { getWorker } from "msw-storybook-addon";
230

231
const worker = getWorker();
232

233
// Check platform-specific features
234
if ('start' in worker) {
235
  // Browser worker - has start() method
236
  console.log('Running in browser');
237
} else if ('listen' in worker) {
238
  // Node.js/React Native server - has listen() method
239
  console.log('Running in Node.js/React Native');
240
}
241
```
242

243
## Advanced Use Cases
244

245
### Conditional Handler Setup
246

247
```typescript
248
import { initialize, getWorker } from "msw-storybook-addon";
249
import { http, HttpResponse } from "msw";
250

251
// Initialize with base handlers
252
initialize({}, [
253
  http.get("/api/config", () => {
254
    return HttpResponse.json({ env: "test" });
255
  })
256
]);
257

258
// Add environment-specific handlers
259
const worker = getWorker();
260
if (process.env.NODE_ENV === 'development') {
261
  worker.use(
262
    http.get("/api/debug", () => {
263
      return HttpResponse.json({ debug: true });
264
    })
265
  );
266
}
267
```
268

269
### Handler Composition
270

271
```typescript
272
import { getWorker } from "msw-storybook-addon";
273
import { http, HttpResponse } from "msw";
274

275
const worker = getWorker();
276

277
// Base handlers
278
const baseHandlers = [
279
  http.get("/api/status", () => {
280
    return HttpResponse.json({ status: "ok" });
281
  })
282
];
283

284
// Feature-specific handlers  
285
const userHandlers = [
286
  http.get("/api/users", () => {
287
    return HttpResponse.json([]);
288
  })
289
];
290

291
// Apply composed handlers
292
worker.use(...baseHandlers, ...userHandlers);
293
```