@custardcream/msw-devtools

Framework Agnostic Devtools for Managing MSW Handlers
Easily manage your mock request handlers

ENGLISH | 한국어

Features

• Framework-Agnostic. Works with any framework, including React, Vue, and more.
• Easily Manage Mock Request Handlers. Add, edit, delete, enable, or disable mock request handlers with ease.
• Use Different Response Data Based on the Situation. Change response data sequentially.
• Export and Import Mock Request Handlers. Easily share mock request handlers in JSON format.
• Live JSON Editing for Instant Management of MSW Request Handlers. Changes made in the Devtools UI are instantly synced with your JSON file. (🔗)

Demo

React.js Demo

Vue.js Demo

Installation

To get started, install the package via npm:

npm install -D @custardcream/msw-devtools msw

Before integrating, make sure you have set up MSW in your project.

npx msw init public

Integrating with React.js

import { setupWorker } from "msw/browser"
import { installMSWDevtools } from "@custardcream/msw-devtools"

const enableMocking = async () => {
  // Exclude devtool from production builds
  if (import.meta.env.DEV) {
    return await installMSWDevtools({
      initialOpen: true, // Automatically open devtool on start
      setupWorker: setupWorker(), // Initialize MSW worker
      options: { // MSW worker options
        onUnhandledRequest: "bypass",
      }
    })
  }
}

// You can use any framework you like
enableMocking().then(() =>
  ReactDomClient.createRoot(document.getElementById("root")!).render(
    <React.StrictMode>
      <App />
    </React.StrictMode>
  )
)

Integrating with Vue.js

const enableMocking = async () => {
  if (import.meta.env.DEV) {
    return await installMSWDevtools({
      initialOpen: true,
      setupWorker: setupWorker(),
      options: {
        onUnhandledRequest: "bypass"
      }
    })
  }
}

enableMocking().then(() => {
  const app = createApp(App)

  app.mount("#app")
})

Handling Dynamic Requests (sequential response)

In various cases, you may want to make response data dynamic.

You can achieve this by using the sequential response feature.

This feature allows you to change the response data for each request sequentially.

Live JSON Editing for Instant Management of MSW Request Handlers

(experimental) This feature is experimental and may change in the future.

Using @custardcream/msw-devtools-server, you can create and update the request handler JSON file in real time through the Devtools UI.

Conversely, you can also directly edit the JSON file to reflect changes in your developing app in real time.

npm install -D @custardcream/msw-devtools-server

// Add isUsingServer option to installMSWDevtools
installMSWDevtools({
  setupWorker: setupWorker(),
  isUsingServer: true // Enable server usage
})

Be sure to start the server before you begin developing your project.

For example, a Vite app can be configured as follows (using concurrently):

{
  "scripts": {
    "start": "concurrently \"msw-devtools-server -o ./mock\" \"vite\""
  }
}

Devtools prioritizes the JSON file over the Request Handler information stored in local storage. Please note that the values stored in local storage may be overwritten when connecting to the server.

CLI Options

• -o, --output <path>: Output file path(or directory) for the generated JSON file. (default: ./mock-list.json)
• -r, --recursive: Read all JSON files in the directory.

Managing Multiple JSON Files

You can manage JSON files by dividing them into folders.

msw-devtools-server --output ./mocks --recursive

mocks
└───folder1
│   │   mock-list.json
│   │   any-name.json
│   │
│   └───subfolder1
│       │   mock-list.json
│       │   ...
│
└───folder2
    │   JSON_FILE_NAME.json

You must specify a directory for the -o, --output option.

Failure to follow the JSON file schema may result in errors.

Created JSON File's Scheme

The JSON file generated by @custardcream/msw-devtools-server follows the following scheme (in typescript):

/**
 * JSON file scheme for managing MSW request handlers
 */
type JsonMock = Array<{
  url: string
  method: MethodOption
  status: StatusOption
  response: JsonMockResponse
  responseDelay: number
  isActivated: boolean
}>

type MethodOption =
  | "get"
  | "post"
  | "put"
  | "patch"
  | "delete"
  | "options"
  | "head"

type StatusOption = "200" | "201" | "400" | "401" | "403" | "404" | "500"

type JsonMockResponse =
  | {
      type: "single"
      response: any
    }
  | {
      type: "sequential"
      response: any[]
    }