Guide · Open source

How to use msw: mock APIs in the browser and Node.js

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

msw (Mock Service Worker) is an open-source JavaScript and TypeScript library that fakes the responses of network requests your app makes. This guide explains how it works in the browser and in Node.js, and shows the basic setup pattern from the project's README. After reading, you will know what to install, how to define request handlers, and where to look for the full documentation.

MSWmswjs/msw · ★ 18.3k · MIT Install options & downloads

Quick start

1Check prerequisites. Install Node.js, which the project lists as the prerequisite.
2Get the project. Clone the repository with git clone https://github.com/mswjs/msw or install it through your package manager as described in the quick start.
3Read the quick start. Open mswjs.io/docs/quick-start to follow the current setup steps.
4Write request handlers. Use http.get, http.post and similar helpers to describe the requests to intercept and the responses to return.
5Start mocking. In the browser, call worker.start() with setupWorker. In Node.js, create a server with setupServer and use it in your tests or server.
6Inspect the result. Make the request in your app and check the mocked response in the browser's Network tab or in your test output.

What does msw do?

Mock Service Worker lets developers fake the responses of network requests made by their app. In the browser it uses the Service Worker API to respond to requests with your mock definitions at the network level, so the app's own code can run unchanged. In Node.js it intercepts requests at a low level instead.

The README describes three main uses: local development, debugging, and automated tests. The same request handlers can be reused across these.

Frontend work before a backend API is ready
One set of mock definitions for unit, integration and end-to-end tests
Mocked responses that show up in the browser DevTools Network tab
Mocking outgoing requests from an Express server during development

Install msw with a package manager

The listed prerequisite is Node.js. The project's README gives a repository clone command, and the library itself is configured with JavaScript or TypeScript code. Check the official documentation for the current install steps, linked from the project homepage at mswjs.io.

Make sure Node.js is installed
Get the project from the repository or your package manager
Read the quick start at mswjs.io/docs/quick-start for the install command

git clone https://github.com/mswjs/msw

Define request handlers

Request handlers describe which requests to intercept and what to respond with. The README shows an Express-like routing syntax, with parameters, wildcards and regular expressions for matching. You can set status codes, headers, cookies, delays, or write custom resolvers.

Handlers are created with the http helpers and passed into a setup function. The example below imports http and HttpResponse from msw/http.

Match paths with parameters such as :id
Return status, headers, cookies or delays
Use custom resolvers when a fixed response is not enough

import { http, HttpResponse } from 'msw/http'
import { setupWorker } from 'msw/browser'

const worker = setupWorker(
  http.get('https://github.com/octocat', ({ request, params, cookies }) => {
    return HttpResponse.json(
      {
        message: 'Mocked response',
      },
      {
        status: 202,
        statusText: 'Mocked status',
      },
    )
  }),
)

await worker.start()

Use msw in the browser

In the browser, call worker.start() to begin mocking by starting the Service Worker. A GET request to the matched URL then returns the mocked response, which you can inspect in the browser's Network tab. Your application does not need to know the response is mocked.

The README notes that request handlers run entirely on the client, so you can use TypeScript, third-party libraries and internal logic when building mocks.

Full browser guide: mswjs.io/docs/integrations/browser
setupWorker API: mswjs.io/docs/api/setup-worker

Use msw in Node.js for tests and Express

In Node.js there are no Service Workers. msw uses a low-level interception algorithm that can run the same request handlers you wrote for the browser. The README's Express example uses setupServer and server.boundary() to scope interception to a single route closure, so mocks apply only while that route is handling a request.

Because msw does not stub fetch or axios, your tests do not need to know that mocking is happening.

Full Node.js guide: mswjs.io/docs/integrations/node
setupServer API: mswjs.io/docs/api/setup-server
boundary API: mswjs.io/docs/api/setup-server/boundary

import express from 'express'
import { http, HttpResponse } from 'msw/http'
import { setupServer } from 'msw/node'

const app = express()
const server = setupServer()

app.get(
  '/checkout/session',
  server.boundary((req, res) => {
    server.use(
      http.get(
        'https://api.stripe.com/v1/checkout/sessions/:id',
        ({ params }) => {
          return HttpResponse.json({
            id: params.id,
            mode: 'payment',
            status: 'open',
          })
        },
      ),
    )

    handleSession(req, res)
  }),
)

Reuse mocks across tests and development

The main design goal stated in the README is a single source of truth. The same mock definitions can serve unit, integration and end-to-end tests, as well as local development and debugging, without adapters or heavy configuration.

Keep handlers in a shared module so every environment imports the same definitions.

Put handlers in one file and import them in both browser and Node.js setup
Use the same handlers for tests and manual development
Official examples: github.com/mswjs/examples

What people use it for

Building a frontend screen before the backend endpoint exists
Testing the same API behavior in unit, integration and end-to-end tests
Debugging a request by inspecting its mocked response in DevTools
Mocking outgoing calls from an Express server during development

Frequently asked questions

Is msw free to use?

The project is released under the MIT licence, as stated on its repository page. Check the LICENSE file in the repository for the full terms.

What do I need to run msw?

The listed prerequisite is Node.js. The library is configured with JavaScript or TypeScript code, so you need to be comfortable writing that.

How does msw work in the browser?

It uses the Service Worker API to intercept requests and respond with your mock definitions at the network level. Your application does not know the response is mocked.

How is msw different from nock or fetch-mock?

The README says msw intercepts requests on the network level and does not stub fetch or axios, so the app's code runs in full. Comparable projects listed for this directory include nock, Polly.js, fetch-mock and Mirage JS; compare them on your own needs.

Can I use msw for end-to-end tests?

The README says the same mock definitions can be reused for unit, integration and end-to-end testing. Check the official docs for the setup each environment needs.

Do I need msw if I only have static fixture files?

Probably not. The project does not describe a fixture-only use case, so a simpler tool may be enough if you do not need request interception.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

msw suits frontend and Node.js developers who want one set of network mocks for development, debugging and tests, and who are comfortable writing JavaScript or TypeScript. If you only need static fixture files with no request interception, or you are not a developer, a simpler tool or one of the comparable projects may be a better fit.

Install options & downloads