Getting Started

msw-dev-tool is a package that helps you control mock logic, modify responses, and monitor API calls with msw.

Installation

New Package Structure (Recommended)

We recommend using the new modular package structure with @msw-dev-tool/core and @msw-dev-tool/react:

pnpm add -D @msw-dev-tool/core @msw-dev-tool/react

npm i @msw-dev-tool/core @msw-dev-tool/react --save-dev

yarn add @msw-dev-tool/core @msw-dev-tool/react --dev

Legacy Package

The msw-dev-tool package is now legacy and will be deprecated in the future. However, it is still stable and fully supported. For new projects, please use the new package structure above.

pnpm add -D msw-dev-tool

npm i msw-dev-tool --save-dev 

yarn add msw-dev-tool --dev 

Install Peer Dependencies

Note To use msw-dev-tool, you need to install the following peer dependencies:

# If you don't use zustand
pnpm add react react-dom
pnpm add -D zustand msw
 
# If you already use zustand
pnpm add react react-dom zustand
pnpm add -D msw

# If you don't use zustand
npm install react react-dom
npm install --save-dev zustand msw
 
# If you already use zustand
npm install react react-dom zustand
npm install --save-dev msw

# If you don't use zustand
yarn add react react-dom
yarn add -D zustand msw
 
# If you already use zustand
yarn add react react-dom zustand
yarn add -D msw

For detailed setup instructions:

• MSW Setup Guide 
• Zustand Setup Guide 

Setup

Using New Package Structure

1. Integrate with msw

Replace MSW’s setupWorker with setupDevToolWorker from @msw-dev-tool/core:

import { setupDevToolWorker } from "@msw-dev-tool/core";
 
export const worker = setupDevToolWorker(...handlers);

Note: Unlike msw, setupDevToolWorker() returns a Promise that resolves to a worker instance.

2. Integrate worker with browser

For detailed information about msw browser integration, please refer to the msw official documentation .

Next.js Integration

1. use use and Suspense to load worker

export const initWorkerPromise =
  typeof window === "undefined"
    ? Promise.resolve()
    : import("@/mock/browser")
        .then(async (mod) => await mod.worker)
        .then((worker) => {
          worker.start({
            onUnhandledRequest: "bypass",
          });
        });

• Import browser worker with Promise.

import { PropsWithChildren, use } from "react";
 
export const MSWProviderContent = ({ children }: PropsWithChildren) => {
  use(initWorkerPromise);
  return children;
};

• To resolve the Promise, use use hook.

import { Suspense } from "react";
 
<Suspense fallback={null}>
  <MSWProviderContent>
    {children}
  </MSWProviderContent>
</Suspense>

• Wrap with Suspense to process the Promise.

2. Add webpack config in next.config.ts

webpack: (config, { isServer }) => {
  // ... other config
  if (isServer) {
    config.resolve.alias["msw/browser"] = false;
  }
  /// --- other config
  return config;
}

• msw/browser has no export in node env. So we need to exclude it from the build process.
• This works fine, as it only ignores validation during the build process.

3. Add DevTool UI

Add the MSWDevTool component and msw-dev-tool.css to your jsx:

import { MSWDevTool } from "@msw-dev-tool/react";
import "@msw-dev-tool/react/msw-dev-tool.css";
 
export default function App() {
  return (
    <>
      {/* Your app components */}
      <MSWDevTool />
    </>
  );
}

Also, you can customize the trigger ui. See Custom Trigger for more details.

Using Legacy Package

1. Integrate with msw

Replace MSW’s setupWorker with setupDevToolWorker from msw-dev-tool:

import { setupDevToolWorker } from "msw-dev-tool";
 
export const worker = setupDevToolWorker(...handlers);

Note: Unlike msw, setupDevToolWorker() returns a Promise that resolves to a worker instance.

2. Integrate worker with browser

For detailed information about msw browser integration, please refer to the msw official documentation .

Next.js Integration

1. use use and Suspense to load worker

export const initWorkerPromise =
  typeof window === "undefined"
    ? Promise.resolve()
    : import("@/mock/browser")
        .then(async (mod) => await mod.worker)
        .then((worker) => {
          worker.start({
            onUnhandledRequest: "bypass",
          });
        });

• Import browser worker with Promise.

import { PropsWithChildren, use } from "react";
 
export const MSWProviderContent = ({ children }: PropsWithChildren) => {
  use(initWorkerPromise);
  return children;
};

• To resolve the Promise, use use hook.

import { Suspense } from "react";
 
<Suspense fallback={null}>
  <MSWProviderContent>
    {children}
  </MSWProviderContent>
</Suspense>

• Wrap with Suspense to process the Promise.

2. Add webpack config in next.config.ts

webpack: (config, { isServer }) => {
  // ... other config
  if (isServer) {
    config.resolve.alias["msw/browser"] = false;
  }
  /// --- other config
  return config;
}

• msw/browser has no export in node env. So we need to exclude it from the build process.
• This works fine, as it only ignores validation during the build process.

3. Add DevTool UI

Add the MSWDevTool component and msw-dev-tool.css to your jsx:

import { MSWDevTool } from "msw-dev-tool";
import "msw-dev-tool/msw-dev-tool.css";
 
export default function App() {
  return (
    <>
      {/* Your app components */}
      <MSWDevTool />
    </>
  );
}

Also, you can customize the trigger ui. See Custom Trigger for more details.

Questions & Support

Have questions? We’re here to help!

• Open a Discussion  for questions and ideas
• Report an Issue  for bugs