rspack-plugin-mock

Rspack and Rsbuild plugin for API mock dev server.

Implement a mock-dev-server in rspack and rsbuild that is fully consistent with vite-plugin-mock-dev-server.

Features

⚡️ Lightweight, Flexible, Fast.
🧲 Not injection-based, non-intrusive to client code.
💡 ESModule/commonjs.
🦾 Typescript.
🔥 HMR
🏷 Support .[cm]?js/ .ts /.json / .json5.
📦 Auto import mock file.
🎨 Support any lib, like mockjs, or do not use it.
📥 Path rule matching, request parameter matching.
⚙️ Support Enabled/Disabled any one of the API mock.
📀 Supports response body content type such as text/json/buffer/stream.
⚖️ Use devServer.proxy in rspack, or server.proxy in rsbuild.
🍕 Support define in the mock file.
⚓️ Support alias in the mock file.
📤 Support multipart content-type, mock upload file.
📥 Support mock download file.
⚜️ Support WebSocket Mock
🗂 Support building small independent deployable mock services.

Install

# npm
npm i -D rspack-plugin-mock
# yarn
yarn add rspack-plugin-mock
# pnp
pnpm add -D rspack-plugin-mock

Usage

In Rspack

// rspack.config.js
import { MockServerPlugin } from 'rspack-plugin-mock'

export default {
  devServer: {
    // The plugin will read the `proxy` option from the `devServer`
    proxy: [
      { context: '/api', target: 'http://example.com' },
    ],
  },
  plugins: [
    new MockServerPlugin(/* pluginOptions */),
  ]
}

In Rsbuild

// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core'
import { pluginMockServer } from 'rspack-plugin-mock/rsbuild'

export default defineConfig({
  server: {
    // The plugin will read the `proxy` option from the `server`
    proxy: {
      '/api': 'http://example.com',
    },
  },
  plugins: [
    pluginMockServer(/* pluginOptions */),
  ],
})

Edit Mock file

By default, write mock data in the mock directory of your project's root directory:

mock/**/*.mock.ts :

import { defineMock } from 'rspack-plugin-mock/helper'

export default defineMock({
  url: '/api/test',
  body: { a: 1, b: 2 }
})

You can write using file formats such as .js, .mjs, .cjs, .ts, .json, .json5.

Methods

MockServerPlugin(pluginOptions)

rspack mock server plugin.

The plugin will read the devServer configuration and inject middleware into the http-server of @rspack/dev-server.

import { MockServerPlugin } from 'rspack-plugin-mock'

export default {
  devServer: {
    // The plugin will read the `proxy` option from the `devServer`
    proxy: [
      { context: '/api', target: 'http://example.com' },
    ],
  },
  plugins: [
    new MockServerPlugin(/* pluginOptions */),
  ]
}

pluginMockServer(pluginOptions)

rsbuild mock server plugin. It is only used in rsbuild.

// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core'
import { pluginMockServer } from 'rspack-plugin-mock/rsbuild'

export default defineConfig({
  server: {
    // The plugin will read the `proxy` option from the `server`
    proxy: {
      '/api': 'http://example.com',
    },
  },
  plugins: [
    pluginMockServer(/* pluginOptions */),
  ],
})

defineMock(options)

options: MockOptions | MockOptions[]

mock options Type helper

import { defineMock } from 'rspack-plugin-mock/helper'

export default defineMock({
  url: '/api/test',
  body: { a: 1, b: 2 }
})

createDefineMock(transformer)

transformer: (mock: MockOptions) => MockOptions

Return a custom defineMock function to support preprocessing of mock config.

import { createDefineMock } from 'rspack-plugin-mock/helper'

const definePostMock = createDefineMock((mock) => {
  mock.url = `/api/post/${mock.url}`
})

export default definePostMock({
  url: 'list', // => '/api/post/list'
  body: [{ title: '1' }, { title: '2' }],
})

Plugin Options

options.prefix

Type: string | string[]
Details:

To configure the path matching rules for http mock services, any request path starting with prefix will be intercepted and proxied. If the prefix starts with ^, it will be recognized as a RegExp.

options.wsPrefix

Type: string | string[]
Details:

Configure path matching rules for WebSocket mock service. Any ws/wss requests with a request path starting with wsPrefix will be intercepted by the proxy. If wsPrefix starts with ^, it will be recognized as a RegExp.

Please avoid having the configurations in wsPrefix appear in devServer.proxy / server.proxy, as this may lead to conflicts in the rules.

options.cwd

Type: string
Default: process.cwd()
Details:

Configure the matching context for include and exclude.

options.include

Type: string | string[]
Default: ['mock/**/*.mock.{js,ts,cjs,mjs,json,json5}']
Details:

glob string matching mock includes files. see picomatch

options.exclude

Type: string | string[]
Default: ['**/node_modules/**', '**/.vscode/**', '**/.git/**']
Details:

glob string matching mock excluded files. see picomatch

options.log

Type: boolean | 'info' | 'warn' | 'error' | 'silent' | 'debug'
Default: info
Details:

Enable log and configure log level

options.reload

Type: boolean
Default: false
Details:

If you want to refresh the page every time you modify a mock file, you can open this option.

options.cors

Type: boolean | CorsOptions
Default: true
Details:

Configure to cors

options.formidableOptions

Type: FormidableOptions
Default: { multiples: true }
Details:

Configure to formidable

options.cookiesOptions

Type: CookiesOptions
Details:

Configure to cookies

options.bodyParserOptions

Type: BodyParserOptions
Details:

Configure to co-body

options.build

Type: boolean | ServerBuildOption

interface ServerBuildOption {
  /**
   * Service startup port
   * @default 8080
   */
  serverPort?: number
  /**
   * Service application output directory
   * @default 'mockServer'
   */
  dist?: string

  /**
   * Service application log level
   * @default 'error'
   */
  log?: LogLevel
}

Default: false
Details:

When you need to build a small mock service, you can configure this option.

Mock Options

options.url

Type: string
Details:

The interface address that needs to be mocked, supported by path-to-regexp for path matching.

options.enabled

Type: boolean
Default: true
Details:

Whether to enable mock for this interface. In most scenarios, we only need to mock some interfaces instead of all requests that have been configured with mock. Therefore, it is important to be able to configure whether to enable it or not.

options.method

Type: Method | Method[]

type Method = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'OPTIONS' | 'HEAD' | 'PATCH'

Default: ['GET', 'POST']
Details:

The interface allows request methods

options.type

Type: 'text' | 'json' | 'buffer' | string
Details:

Response body data type. And also support types included in mime-db.

When the response body returns a file and you are not sure which type to use, you can pass the file name as the value. The plugin will internally search for matching content-type based on the file name suffix.

options.headers

Type: object | (request: MockRequest) => object | Promise<object>
Default: { 'Content-Type': 'application/json' }
Details:

Configure the response body headers

options.status

Type: number
Default: 200
Details:

Configure Response Header Status Code

options.statusText

Type: string
Default: "OK"
Details:

Configure response header status text

options.delay

Type: number | [number, number]
Default: 0
Details:

Configure response delay time, If an array is passed in, it represents the range of delay time.

unit: ms

options.body

Type: Body | (request: MockRequest) => Body | Promise<Body>
```
type Body = string | object | Buffer | Readable
```
Details:

Configure response body data content. body takes precedence over response.

options.response

Type: (req: MockRequest, res: MockResponse, next: (err?: any) => void) => void | Promise<void>
Details:

If you need to set complex response content, you can use the response method, which is a middleware. Here, you can get information such as req and res of the http request, and then return response data through res.write() | res.end(). Otherwise, you need to execute next() method. In req, you can also get parsed request information such as query, params, body and refererQuery.

options.cookies

Type: CookiesOptions | (request: MockRequest) => CookiesOptions | Promise<CookiesOptions>

type CookiesOptions = Record<string, CookieValue>

type CookieValue = string | [string, SetCookie]

Details:

Configure response body cookies

options.validator

Type: Validator | (request: MockRequest) => boolean

interface Validator {
  /**
   * The query string located after `?` in the request address has been parsed into JSON.
   */
  query: Record<string, any>
  /**
   * The queryString located after `?` in the referer request has been parsed as JSON.
   */
  refererQuery: Record<string, any>
  /**
   * Body data in the request
   */
  body: Record<string, any>
  /**
   * The params parameter parsed from the `/api/id/:id` in the request address.
   */
  params: Record<string, any>
  /**
   * headers data in the request
   */
  headers: Headers
}

Details:

Request Validator

Sometimes, for the same API request, data needs to be returned based on different request parameters.

However, if all of this is written in a single mock's body or response, the content can become cumbersome and difficult to manage. The function of a validator allows you to configure multiple mocks with the same URL simultaneously and determine which mock should be used through validation.

options.ws

Type: boolean
Default: false
Details:

Enable WebSocket interface simulation

options.setup

Type: (wss: WebSocketServer, ctx: WebSocketSetupContext) => void
Details:

Configure Websocket Server

interface WebSocketSetupContext {
  /**
   * When defining WSS, you may perform some automatic or looping tasks.
   * However, when hot updating, the plugin will re-execute `setup()`,
   * which may result in duplicate registration of listening events and looping tasks
   * such as setTimeout. You can use `onCleanup()` to clear these automatic or looping tasks.
   */
  onCleanup: (cleanup: () => void) => void
}

Types

export type MockRequest = http.IncomingMessage & ExtraRequest

export type MockResponse = http.ServerResponse<http.IncomingMessage> & {
  /**
   * Set cookie in response
   * @see [cookies](https://github.com/pillarjs/cookies#cookiessetname--values--options)
   */
  setCookie: (
    name: string,
    value?: string | null,
    option?: Cookies.SetOption,
  ) => void
}

interface ExtraRequest {
  /**
   * The query string located after `?` in the request address has been parsed into JSON.
   */
  query: Record<string, any>
  /**
   * The queryString located after `?` in the referer request has been parsed as JSON.
   */
  refererQuery: Record<string, any>
  /**
   * Body data in the request
   */
  body: Record<string, any>
  /**
   * The params parameter parsed from the `/api/id/:id` in the request address.
   */
  params: Record<string, any>
  /**
   * headers data in the request
   */
  headers: Headers
  /**
   * Get the cookie carried in the request.
   * @see [cookies](https://github.com/pillarjs/cookies#cookiesgetname--options)
   */
  getCookie: (name: string, option?: Cookies.GetOption) => string | undefined
}

Examples

exp: Match /api/test, And returns a response body content with empty data

export default defineMock({
  url: '/api/test',
})

exp: Match /api/test , And returns a static content data

export default defineMock({
  url: '/api/test',
  body: { a: 1 },
})

exp: Only Support GET Method

export default defineMock({
  url: '/api/test',
  method: 'GET'
})

exp: In the response header, add a custom header and cookie

export default defineMock({
  url: '/api/test',
  headers: { 'X-Custom': '12345678' },
  cookies: { 'my-cookie': '123456789' },
})

export default defineMock({
  url: '/api/test',
  headers({ query, body, params, headers }) {
    return { 'X-Custom': query.custom }
  },
  cookies() {
    return { 'my-cookie': '123456789' }
  }
})

exp: Define multiple mock requests for the same URL and match valid rules with validators

export default defineMock([
  // Match /api/test?a=1
  {
    url: '/api/test',
    validator: {
      query: { a: 1 },
    },
    body: { message: 'query.a == 1' },
  },
  // Match /api/test?a=2
  {
    url: '/api/test',
    validator: {
      query: { a: 2 },
    },
    body: { message: 'query.a == 2' },
  },
  {
    // `?a=3` will resolve to `validator.query`
    url: '/api/test?a=3',
    body: { message: 'query.a == 3' }
  },
  // Hitting the POST /api/test request, and in the request body,
  // field a is an array that contains items with values of 1 and 2.
  {
    url: '/api/test',
    method: ['POST'],
    validator: { body: { a: [1, 2] } }
  }
])

exp: Response Delay

export default defineMock({
  url: '/api/test',
  delay: 6000, // delay 6 seconds
})

exp: The interface request failed

export default defineMock({
  url: '/api/test',
  status: 502,
  statusText: 'Bad Gateway'
})

exp: Dynamic route matching

export default defineMock({
  url: '/api/user/:userId',
  body({ params }) {
    return { userId: params.userId }
  }
})

The userId in the route will be resolved into the request.params object.

exp: Use the buffer to respond data

import { Buffer } from 'node:buffer'

// Since the default value of type is json,
// although buffer is used for body during transmission,
// the content-type is still json.
export default defineMock({
  url: 'api/buffer',
  body: Buffer.from(JSON.stringify({ a: 1 }))
})

// When the type is buffer, the content-type is application/octet-stream.
// The data passed in through body will be converted to a buffer.
export default defineMock({
  url: 'api/buffer',
  type: 'buffer',
  // Convert using Buffer.from(body) for internal use
  body: { a: 1 }
})

exp: Response file type

Simulate file download, and pass in the file reading stream.

import { createReadStream } from 'node:fs'

export default defineMock({
  url: '/api/download',
  // When you are unsure of the type, you can pass in the file name for internal parsing by the plugin.
  type: 'my-app.dmg',
  body: () => createReadStream('./my-app.dmg')
})

<a href="/api/download" download="my-app.dmg">Download File</a>

exp: Use mockjs:

import Mock from 'mockjs'

export default defineMock({
  url: '/api/test',
  body: Mock.mock({
    'list|1-10': [{
      'id|+1': 1
    }]
  })
})

You need install mockjs

exp: Use response to customize the response

export default defineMock({
  url: '/api/test',
  response(req, res, next) {
    const { query, body, params, headers } = req
    console.log(query, body, params, headers)

    res.status = 200
    res.setHeader('Content-Type', 'application/json')
    res.end(JSON.stringify({
      query,
      body,
      params,
    }))
  }
})

exp: Use json / json5

{
  "url": "/api/test",
  "body": {
    "a": 1
  }
}

exp: multipart, upload files.

use formidable to support.

<form action="/api/upload" method="post" enctype="multipart/form-data">
  <p>
    <span>file: </span>
    <input type="file" name="files" multiple="multiple">
  </p>
  <p>
    <span>name:</span>
    <input type="text" name="name" value="mark">
  </p>
  <p>
    <input type="submit" value="submit">
  </p>
</form>

fields files mapping to formidable.File

export default defineMock({
  url: '/api/upload',
  method: 'POST',
  body(req) {
    const body = req.body
    return {
      name: body.name,
      files: body.files.map((file: any) => file.originalFilename),
    }
  },
})

exp: Graphql

import { buildSchema, graphql } from 'graphql'

const schema = buildSchema(`
type Query {
  hello: String
}
`)
const rootValue = { hello: () => 'Hello world!' }

export default defineMock({
  url: '/api/graphql',
  method: 'POST',
  body: async (request) => {
    const source = request.body.source
    const { data } = await graphql({ schema, rootValue, source })
    return data
  },
})

fetch('/api/graphql', {
  method: 'POST',
  body: JSON.stringify({ source: '{ hello }' })
})

exp: WebSocket Mock

// ws.mock.ts
export default defineMock({
  url: '/socket.io',
  ws: true,
  setup(wss, { onCleanup }) {
    const wsMap = new Map()
    wss.on('connection', (ws, req) => {
      const token = req.getCookie('token')
      wsMap.set(token, ws)
      ws.on('message', (raw) => {
        const data = JSON.parse(String(raw))
        if (data.type === 'ping')
          return
        // Broadcast
        for (const [_token, _ws] of wsMap.entires()) {
          if (_token !== token)
            _ws.send(raw)
        }
      })
    })
    wss.on('error', (err) => {
      console.error(err)
    })
    onCleanup(() => wsMap.clear())
  }
})

// app.ts
const ws = new WebSocket('ws://localhost:3000/socket.io')
ws.addEventListener('open', () => {
  setInterval(() => {
    // heartbeat
    ws.send(JSON.stringify({ type: 'ping' }))
  }, 1000)
}, { once: true })
ws.addEventListener('message', (raw) => {
  console.log(raw)
})

Mock Services

In some scenarios, it may be necessary to use the data provided by mock services for display purposes, but the project may have already been packaged, built and deployed without support from rspack/rsbuild and this plugin's mock service. Since this plugin supports importing various node modules in mock files at the design stage, the mock file cannot be inline into client build code.

The plugin support for builds a small independent mock service application that can be deployed to relevant environments during production build. This can then be forwarded through other HTTP servers like Nginx to actual ports for mock support.

The default output is built into the directory dist/mockServer, generating files as follows:

./mockServer
├── index.js
├── mock-data.js
└── package.json

In this directory, execute npm install to install dependencies, and then execute npm start to start the mock server.

The default port is 8080.

You can access related mock interfaces through localhost:8080/.

Links

License

rspack-plugin-mock is licensed under the MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 72 Commits
.github/workflows		.github/workflows
.husky		.husky
.vscode		.vscode
examples		examples
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

License

pengzhanbo/rspack-plugin-mock

Folders and files

Latest commit

History

Repository files navigation

rspack-plugin-mock

Features

Install

Usage

Edit Mock file

Methods

MockServerPlugin(pluginOptions)

pluginMockServer(pluginOptions)

defineMock(options)

createDefineMock(transformer)

Plugin Options

options.prefix

options.wsPrefix

options.cwd

options.include

options.exclude

options.log

options.reload

options.cors

options.formidableOptions

options.cookiesOptions

options.bodyParserOptions

options.build

Mock Options

options.url

options.enabled

options.method

options.type

options.headers

options.status

options.statusText

options.delay

options.body

options.response

options.cookies

options.validator

options.ws

options.setup

Types

Examples

Mock Services

Links

License

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 10

Languages