vite-plugin-mock-dev-server

Vite Plugin for API mock dev server.

English | 简体中文

Features

• ⚡️ Lightweight, Flexible, Fast.
• 🧲 Not injection-based, non-intrusive to client code.
• 💡 Pure ESModule.
• 🦾 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 server.proxy
• 🍕 Support viteConfig.define and env in the mock file.
• ⚓️ Support viteConfig.resolve.alias in the mock file.
• 🌈 Support vite preview mode.
• 📤 Support multipart content-type, mock upload file.
• 📥 Support mock download file.
• ⚜️ Support WebSocket Mock and Server-Sent Events Mock
• 📝 Support recording and replay requests
• 🗂 Support building small independent deployable mock services.

Documentation

See the documentation for more details.

The current document is for the v2 version of the plugin. If you are using the v1 version, please refer to the Migration Guide.

Install

# npm
npm i -D vite-plugin-mock-dev-server
yarn
yarn add vite-plugin-mock-dev-server
pnpm
pnpm add -D vite-plugin-mock-dev-server

Usage

vite.config.ts

import { defineConfig } from 'vite'
import { mockDevServerPlugin } from 'vite-plugin-mock-dev-server'
export default defineConfig({
  plugins: [mockDevServerPlugin(/ plugin options /)],
  // The fields defined here can also be used in mock.
  define: {},
  server: {
    // plugin will read server.proxy
    proxy: {
      '^/api': { target: 'http://example.com' },
    },
  },
})

The plugin will read the configuration of server.proxy or options.prefix, and enable mock matching for matched URLs.

The plugin will also read the define configuration, which supports direct use in mock files.

Edit Mock File

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

mock/*/.mock.ts :

import { defineMock } from 'vite-plugin-mock-dev-server'
export default defineMock({
  url: '/api/user/:id',
  body: { a: 1, b: 2 },
})

Methods

mockDevServerPlugin(pluginOptions)

vite plugin

vite.config.ts

import { defineConfig } from 'vite'
import { mockDevServerPlugin } from 'vite-plugin-mock-dev-server'
export default defineConfig({
  plugins: [mockDevServerPlugin({/ plugin options /})],
})

defineMock(mockOptions)

Mock Options Type Helper

import { defineMock } from 'vite-plugin-mock-dev-server'
export default defineMock({
  url: '/api/test',
  body: {},
})

createDefineMock(transformer)

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

import path from 'node:path'
import { createDefineMock } from 'vite-plugin-mock-dev-server'
// Preprocessed mock url
const defineAPIMock = createDefineMock((mock) => {
  mock.url = path.join('/api', mock.url)
})
export default defineApiMock({
  url: '/test', // Complete as '/api/test'
})

createSSEStream(req, res)

Create a Server-sent events write stream to support mocking EventSource.

import { createSSEStream, defineMock } from 'vite-plugin-mock-dev-server'
export default defineMock({
  url: '/api/sse',
  response: (req, res) => {
    const sse = createSSEStream(req, res)
    sse.write({ event: 'message', data: { message: 'hello world' } })
    sse.end()
  },
})

Plugin Options

enabled

• Type: boolean
• Default: true
• Details:

prefix

• Type: string | string[]
• Default: []
• Details:

> In general, server.proxy is sufficient to meet the needs. Adding this item is for compatibility with certain scenarios.

wsPrefix

• Type: string | string[]
• Default: []
• Details:

If the value of wsPrefix starts with ^, it will be recognized as a RegExp.

> Different from using viteConfig.server.proxy by default for http mock, websocket mock does not use the ws-related configuration in viteConfig.server.proxy. Also, rules configured in wsPrefix cannot be configured simultaneously in viteConfig.server.proxy, as it will cause conflicts when starting the vite server because multiple instances of WebSocketServer cannot be implemented for the same request. > This conflict is neither a problem with Vite nor with the plugin; it belongs to a reasonable error type. When switching between WebSocket Mock and WebSocket Proxy, please pay attention to avoid duplicate configurations that may cause conflicts.

cwd

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

dir

• Type: string
• Default: 'mock'
• Details:

include

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

exclude

• Type: string | string[]
• Default： ['/node_modules/']
• Details:

reload

• Type: boolean
• Default: false
• Details:

activeScene

• Type: string | string[]
• Default: ''
• Details:

Only mocks whose scene intersects with this value (or have no scene configured) will be considered for matching. Can be overridden per-request via the X-Mock-Scene header.

cors

• Type: boolean | CorsOptions
• Default: true
• Details:

Configure to cors, see cors

log

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

formidableOptions

• Type: formidable.Options
• Details:

example: Configure to file upload dir

MockDevServerPlugin({
    formidableOptions: {
      uploadDir: path.join(process.cwd(), 'uploads'),
    },
  })

cookiesOptions

• Type: CookiesOptions
• Details:

bodyParserOptions

• Type: BodyParserOptions
• Details:

build

• Type: boolean | ServerBuildOptions
• Default: false
• Details:

interface ServerBuildOptions {
    /**
     * server port
     * @default 8080
     */
    serverPort?: number
    /**
     * build output dir
     * @default 'mockServer'
     */
    dist?: string
    /**
     * log level
     * @default 'error'
     */
    log?: LogLevel
  }

record

• Type: false | RecordOptions
• Default: false
• Details：

Based on vite.server.proxy, the plugin records request data proxied by http-proxy. After receiving a response, the plugin will record the request data and response data to the specified directory.

interface RecordOptions {
    /**
     * Whether to enable the record feature
     * - true: Enable, automatically record proxy responses
     * - false: Disable (default)
     * @default false
     */
    enabled?: boolean
    /**
     * Filter requests to record
     * - Function: Custom filter function, return true to record
     * - Object: Include/exclude patterns with glob or path-to-regexp mode
     * @example
     *

/
    filter?:
      | ((req: RecordedReq) => boolean)
      | {
          /**
           * Include the request links that need to be recorded
           *
           * String: Glob pattern or path-to-regexp pattern
           * (Use the mode option to set the mode, default is glob)
           */
          include?: string | string[]
          /**
           * Exclude request links that do not need to be recorded
           *
           * String: Glob pattern or path-to-regexp pattern
           * (Use the mode option to set the mode, default is glob)
           */
          exclude?: string | string[]
          /**
           * Matching mode for include/exclude patterns
           * - 'glob': Glob pattern matching (default)
           * - 'path-to-regexp': Path-to-regexp pattern matching
           */
          mode: 'glob' | 'path-to-regexp'
        }

/**
     * Directory to store recorded data
     * Relative to project root
     * @default 'mock/.recordings'
     */
    dir?: string
    /**
     * Whether to overwrite existing recorded data
     * - true: Overwrite old data for the same request (default)
     * - false: Keep old data, do not record new data
     * @default true
     */
    overwrite?: boolean
    /**
     * Expiration time for recorded data in seconds
     * - 0: Never expire (default)
     * - Positive number: Expire after specified seconds
     * @default 0
     */
    expires?: number
    /**
     * Status codes to record
     * - Empty array: Record all status codes (default)
     * - Specify one or more status codes to filter
     * @default []
     */
    status?: number | number[]
    /**
     * Should a .gitignore be added to the recording directory
     * - true: Add (default)
     * - false: Do not add
     * @default true
     */
    gitignore?: boolean
  }

replay

• Type: boolean
• Default: false
• Details：

Replay works independently of recording, replay: true can be used with record: { enabled: false } to reuse existing recordings. A warning is printed at startup when recording is disabled.

priority

• Type: MockMatchPriority
• Details:

Mock Options

http mock

import { defineMock } from 'vite-plugin-mock-dev-server'
export default defineMock({
  url: '/api/test',
  body: { message: 'hello world' },
})

websocket mock

import { defineMock } from 'vite-plugin-mock-dev-server'
export default defineMock({
  url: '/socket.io',
  ws: true,
  setup(wss) {
    wss.on('connection', (ws, req) => {
      console.log('connected')
    })
  },
})

options.url

• Type: string
• Details:

options.enabled

• Type: boolean
• Default: true
• Details:

options.scene

• Type: string | string[]
• Default: ''
• Details:

When not configured, the mock is universal and always matches regardless of active scenario.When configured, the mock only matches when at least one of its scenarios matches one of the active scenarios.

options.method

• Type: Method | Method[]

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

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

options.type

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

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