npm / msw
msw
What changed in msw 2 to 3, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-17.
17 breaking14 new APIs and options3 behavior and defaults2 tooling34 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initmsw 335 changes
Breaking changes 15
The Content-Length request header is removed by bypass().
MSW no longer manages cookies in Node.js; cookie behavior follows the environment default. Browser behavior is unchanged.
The defineNetwork() API is the replacement for the removed handleRequest() utility.
MSW is now ESM-only, affecting how projects load and bundle the package.
MSW no longer patches setTimeout; advance fake timers normally for delayed mocked responses to resolve.
file:// requests now throw in Node.js, matching fetch behavior because fetch does not support them.
GraphQLLinkHandlers is renamed to GraphQLLink.
The handleRequest() utility is removed; use defineNetwork() instead.
Upgrade requests made via fetch() now throw in Node.js, matching fetch behavior because fetch does not support them.
The msw/native entrypoint is removed in favor of @msw/react-native.
The minimal supported Node.js version is v22; Node.js v18 and v20 support is deprecated.
The onUnhandledRequest option is renamed to onUnhandledFrame.
This now returns null in handlers in all environments; use the cookies resolver argument for cookie-based logic.
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.
The WebSocket connection life cycle event is renamed from connection to websocket:connection.
New APIs and options 7
GraphQL is exported from msw/graphql and handled as an optional peer dependency.
MSW now supports GraphQL subscriptions.
MSW now supports GraphQL v17.0.
Import individual utilities such as delay or passthrough from msw/utils for a smaller bundle footprint.
MSW can now intercept page navigations and form submissions.
A new WebSocket life cycle event lets consumers listen to connection errors.
A new WebSocket Extension API enables better custom experiences.
Behavior and default changes 2
Intercepted request headers can now be modified in passthrough scenarios.
worker.stop() now returns a Promise; awaiting it matters only in in-flight critical scenarios.
Tooling 2
MSW now supports TypeScript v6.0 and v7.0.
MSW adds a Vite plugin.
Fixes and other changes 9
Network sources expose network context on enable.
Reset handlers are disposed of when reset, preventing them from remaining active.
Supports virtual:msw imports in Vitest.
Treats CONNECT requests as the transport mechanism.
Fixed localStorage cookie persistence causing maximum quota exceeded errors.
Fixed in-flight requests being incorrectly passed through when performed before calling worker.stop().
Various issues related to network interception in Node.js are fixed.
MSW now supports Node.js v24 and v26.
Preventing page closure via a beforeunload listener no longer unregisters the MSW worker.
msw 235 changes
Breaking changes 2
In Node.js, toPublicUrl now removes search parameters.
The browser and react-native export conditions are ordered lower, changing package export resolution.
New APIs and options 7
Adds the finalize API for handler cleanup.
Support handling connection upgrades with ws.onUpgrade.
Adds a public test() method to WebSocketHandler.
Use the network source architecture through defineNetwork.
Exports the AnyHandler type for developers to use.
Exports the GraphQLLinkHandlers type for use by developers.
Adds support for server-sent events (SSE).
Behavior and default changes 1
The SSE response stream now invokes finalize when it ends.
Fixes and other changes 25
Logging for concurrent requests is now handled properly.
Prevents event forwarding manually.
All frame listeners are removed when the client closes.
Prevents a frame abort listener leak.
Exports the NetworkApi type so developers can use it.
Fixes exporting default handler controllers.
Cookies are forwarded only when the response is used.
User-provided responses are no longer cloned.
Generator state is reset when .resetHandlers() or .restoreHandlers() is called.
The underlying SSE stream now respects request.signal, allowing request cancellation to affect the stream.
Prevent
infinitemode from throwing.Life-cycle events are now annotated correctly.
WebSocket connections are no longer logged in the console when there are no matching event handlers.
URL matching now supports wildcard ports.
GraphQL supports responses with the application/graphql-response+json content type.
The postinstall script now handles special characters, preventing installation issues in environments where they occur.
In Node.js, infinite delays no longer leave open handles.
ws.link supports relative URLs.
Updated the interceptors dependency to fix a memory leak.
Supports TypedDocumentString as a request predicate.
The SSE worker now respects the quiet option.
Server-Sent Events now handle multi-line messages.
Handles incomplete localStorage in Node.js v25.
Types used in HttpHandler are now published for developers to use.
Fixes response init in response:* events.