# What changed in msw

> 70 changes in msw 2 to 3 from its official release notes, upgrade guides and advisories: 17 breaking, 14 new APIs and options. Each one cited. Sources checked 2026-10-17. HTML: https://unstale.sh/npm/msw/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## msw 3

### Breaking changes

- The Content-Length request header is removed by bypass(). (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- MSW no longer manages cookies in Node.js; cookie behavior follows the environment default. Browser behavior is unchanged. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- The defineNetwork() API is the replacement for the removed handleRequest() utility. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- MSW is now ESM-only, affecting how projects load and bundle the package. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- MSW no longer patches setTimeout; advance fake timers normally for delayed mocked responses to resolve. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- file:// requests now throw in Node.js, matching fetch behavior because fetch does not support them. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- GraphQLLinkHandlers is renamed to GraphQLLink. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- The handleRequest() utility is removed; use defineNetwork() instead. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- Upgrade requests made via fetch() now throw in Node.js, matching fetch behavior because fetch does not support them. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- The msw/native entrypoint is removed in favor of @msw/react-native. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- The minimal supported Node.js version is v22; Node.js v18 and v20 support is deprecated. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- The onUnhandledRequest option is renamed to onUnhandledFrame. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- This now returns null in handlers in all environments; use the cookies resolver argument for cookie-based logic. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- TypeScript 5.9 is the minimum supported version; support for 5.1 and 5.2 is deprecated, and versions 6.0 and 7.0 are supported. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- The WebSocket connection life cycle event is renamed from connection to websocket:connection. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)

### New APIs and options

- GraphQL is exported from msw/graphql and handled as an optional peer dependency. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- MSW now supports GraphQL subscriptions. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- MSW now supports GraphQL v17.0. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- Import individual utilities such as delay or passthrough from msw/utils for a smaller bundle footprint. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- MSW can now intercept page navigations and form submissions. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- A new WebSocket life cycle event lets consumers listen to connection errors. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- A new WebSocket Extension API enables better custom experiences. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)

### Behavior and default changes

- Intercepted request headers can now be modified in passthrough scenarios. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- worker.stop() now returns a Promise; awaiting it matters only in in-flight critical scenarios. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)

### Tooling

- MSW now supports TypeScript v6.0 and v7.0. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- MSW adds a Vite plugin. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)

### Fixes and other changes

- Network sources expose network context on enable. (3.0.3) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.3)
- Reset handlers are disposed of when reset, preventing them from remaining active. (3.0.3) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.3)
- Supports virtual:msw imports in Vitest. (3.0.2) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.2)
- Treats CONNECT requests as the transport mechanism. (3.0.1) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.1)
- Fixed localStorage cookie persistence causing maximum quota exceeded errors. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- Fixed in-flight requests being incorrectly passed through when performed before calling worker.stop(). (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- Various issues related to network interception in Node.js are fixed. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- MSW now supports Node.js v24 and v26. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)
- Preventing page closure via a beforeunload listener no longer unregisters the MSW worker. (3.0.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v3.0.0)

## msw 2

### Breaking changes

- In Node.js, toPublicUrl now removes search parameters. (2.12.3) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.3)
- The browser and react-native export conditions are ordered lower, changing package export resolution. (2.12.2) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.2)

### New APIs and options

- Adds the finalize API for handler cleanup. (2.14.4) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.14.4)
- Support handling connection upgrades with ws.onUpgrade. (2.14.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.14.0)
- Adds a public test() method to WebSocketHandler. (2.13.6) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.13.6)
- Use the network source architecture through defineNetwork. (2.13.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.13.0)
- Exports the AnyHandler type for developers to use. (2.12.10) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.10)
- Exports the GraphQLLinkHandlers type for use by developers. (2.12.7) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.7)
- Adds support for server-sent events (SSE). (2.12.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.0)

### Behavior and default changes

- The SSE response stream now invokes finalize when it ends. (2.15.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.15.0)

### Fixes and other changes

- Logging for concurrent requests is now handled properly. (2.14.7) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.14.7)
- Prevents event forwarding manually. (2.14.6) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.14.6)
- All frame listeners are removed when the client closes. (2.14.5) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.14.5)
- Prevents a frame abort listener leak. (2.14.3) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.14.3)
- Exports the NetworkApi type so developers can use it. (2.14.2) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.14.2)
- Fixes exporting default handler controllers. (2.14.1) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.14.1)
- Cookies are forwarded only when the response is used. (2.14.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.14.0)
- User-provided responses are no longer cloned. (2.14.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.14.0)
- Generator state is reset when .resetHandlers() or .restoreHandlers() is called. (2.13.5) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.13.5)
- The underlying SSE stream now respects request.signal, allowing request cancellation to affect the stream. (2.13.4) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.13.4)
- Prevent `infinite` mode from throwing. (2.13.2) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.13.2)
- Life-cycle events are now annotated correctly. (2.13.1) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.13.1)
- WebSocket connections are no longer logged in the console when there are no matching event handlers. (2.13.0) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.13.0)
- URL matching now supports wildcard ports. (2.12.14) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.14)
- GraphQL supports responses with the application/graphql-response+json content type. (2.12.13) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.13)
- The postinstall script now handles special characters, preventing installation issues in environments where they occur. (2.12.12) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.12)
- In Node.js, infinite delays no longer leave open handles. (2.12.11) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.11)
- ws.link supports relative URLs. (2.12.9) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.9)
- Updated the interceptors dependency to fix a memory leak. (2.12.8) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.8)
- Supports TypedDocumentString as a request predicate. (2.12.7) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.7)
- The SSE worker now respects the quiet option. (2.12.6) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.6)
- Server-Sent Events now handle multi-line messages. (2.12.5) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.5)
- Handles incomplete localStorage in Node.js v25. (2.12.4) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.4)
- Types used in HttpHandler are now published for developers to use. (2.12.3) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.3)
- Fixes response init in response:* events. (2.12.1) — [release notes](https://github.com/mswjs/msw/releases/tag/v2.12.1)