mock-service-plugin

English | 中文

A powerful Mock service plugin that supports multiple frameworks and build tools, providing flexible interface simulation capabilities.

Features

• 🚀 Support for multiple build tools
  • Webpack 4/5
  • Vite
  • Vue CLI
  • Create React App (CRA)
• 🎯 Support for multiple frameworks
  • Vue
  • React
• 🔥 Powerful feature support
  • RESTful API support
  • Streaming responses (SSE/EventStream)
  • Multiple response formats (JSON/XML/CSV/Text etc.)
  • Dynamic route parameters
  • Request method matching (GET/POST/PUT/DELETE etc.)
• 💡 Easy to use
  • Zero configuration startup
  • Hot reload support
  • Friendly debugging interface

Quick Start

Installation

npm install mock-service-plugin --save-dev

yarn add mock-service-plugin --dev

Basic Configuration

const MockServicePlugin = require("mock-service-plugin");

module.exports = {
  plugins: [
    new MockServicePlugin({
      mockDir: path.join(__dirname, "./mocks"), // mock data directory
      port: 3000, // mock service port
    }),
  ],
};

Mock Data Specification

Basic Format

/**
 * @url /api/users
 * @method GET
 */
{
  "code": 200,
  "data|5-10": [{
    "id": "@id",
    "name": "@cname",
    "email": "@email"
  }],
  "message": "success"
}

Header Annotation Description

/**
 * @url /api/users
 * @method GET
 */

• @url: Interface path (required)
• @method: Request method (optional, supports GET/POST/PUT/DELETE etc., case-insensitive)

Request Method Matching

1. Specify request method:

/**
 * @url /api/users
 * @method POST
 */
{
  "code": 200,
  "message": "Created successfully"
}

2. Support all request methods (without @method):

/**
 * @url /api/users
 */
{
  "code": 200,
  "data": {
    "id": "@id",
    "name": "@cname"
  }
}

3. RESTful API example:

// POST request
/**
 * @url /api/users
 * @method POST
 */
{
  "code": 200,
  "message": "Created successfully"
}

// GET request
/**
 * @url /api/users/:id
 * @method GET
 */
{
  "id": "@id",
  "name": "@cname"
}

// PUT request
/**
 * @url /api/users/:id
 * @method PUT
 */
{
  "code": 200,
  "message": "Updated successfully"
}

// DELETE request
/**
 * @url /api/users/:id
 * @method DELETE
 */
{
  "code": 200,
  "message": "Deleted successfully"
}

Supported Response Types

| Mock file extension | Content-Type | Description | | ------------------- | ---------------------- | ----------------- | | .json | application/json | JSON data format | | .txt | text/plain | Plain text format | | .html | text/html | HTML document | | .xml | application/xml | XML data format | | .csv | text/csv | CSV table data | | .md | text/markdown | Markdown document | | .pdf | application/pdf | PDF document | | .png | image/png | PNG image | | .jpg/.jpeg | image/jpeg | JPEG image | | .gif | image/gif | GIF image | | .svg | image/svg+xml | SVG vector image | | .css | text/css | CSS stylesheet | | .js | application/javascript | JavaScript code | | .yaml/.yml | application/x-yaml | YAML config file | | .sse | text/event-stream | SSE event stream |

Mock File Examples

JSON Format (mock.json)

/**
 * @url /api/users
 * @method GET
 */
{
  "code": 200,
  "data": {
    "name": "@cname",
    "age": "@integer(18, 60)"
  }
}

Text Format (mock.txt)

/**
 * @url /api/text
 * @method GET
 */
This is a mock text content, supporting multiple lines.
Second line content.
Third line content.

CSS Format (mock.css)

/**
 * @url /api/styles
 * @method GET
 */
.container {
  width: 100%;
  max-width: 1200px;
  margin: 0 auto;
  padding: 20px;
}

Markdown Format (mock.md)

/**
 * @url /api/markdown
 * @method GET
 */
# Heading 1
## Heading 2
- List item 1
- List item 2

YAML Format (mock.yaml)

/**
 * @url /api/config
 * @method GET
 */
version: 1.0;
settings: debug: true;
timeout: 30;

CSV Format (mock.csv)

/**
 * @url /api/data
 * @method GET
 */
(id, name, age);
(1, John, 25);
(2, Jane, 30);
(3, Bob, 28);

XML Format (mock.xml)

/**
 * @url /api/xml
 * @method GET
 */
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <user>
    <name>John</name>
    <age>25</age>
  </user>
</root>

JavaScript Format (mock.js)

/**
 * @url /api/script
 * @method GET
 */
function greeting(name) {
  return `Hello, ${name}!`;
}

For image type responses, you can directly return the image file path:

/**
 * @url /api/avatar
 * @content-type image/png
 */
"/path/to/avatar.png";

Advanced Features

RESTful API Support

/**
 * @url /api/users/:id
 * @method GET
 */
{
  "id": "@id",
  "name": "@cname",
  "email": "@email"
}

Streaming Response

File extension: mock.sse

/**
 * @url /api/stream
 */
{
  "interval": "@integer(100,500)",
  "items|10": [{
    "id": "@increment(1)",
    "data": {
      "content": "@csentence(3,10)"
    }
  }]
}

Framework Integration

Vue Project

// vue.config.js
const MockServicePlugin = require("mock-service-plugin");

module.exports = {
  configureWebpack: {
    plugins: [
      new MockServicePlugin({
        mockDir: path.join(__dirname, "./mocks"),
        port: 9090,
      }),
    ],
  },
  devServer: {
    proxy: {
      "/api": {
        target: "http://localhost:9090",
        pathRewrite: { "^/api": "" },
      },
    },
  },
};

React Project (CRA)

Using craco

// craco.config.js
const MockServicePlugin = require("mock-service-plugin");

module.exports = {
  webpack: {
    plugins: {
      add: [
        new MockServicePlugin({
          mockDir: path.join(__dirname, "./mocks"),
          port: 9090,
        }),
      ],
    },
  },
};

Using customize-cra

// config-overrides.js
const { override, addWebpackPlugin } = require("customize-cra");
const MockServicePlugin = require("mock-service-plugin");

module.exports = override(
  addWebpackPlugin(
    new MockServicePlugin({
      mockDir: path.join(__dirname, "./mocks"),
      port: 9090,
    })
  )
);

Vite Project

// vite-mock-plugin.ts file
import { startServer } from 'mock-service-plugin'
import { createServer } from 'net'
import { join } from 'path'

function isPortTaken(port: number) {
  return new Promise((resolve) => {
    const server = createServer()

    server.once('error', (err: { code: string }) => {
      if (err.code === 'EADDRINUSE') {
        resolve(true)
      } else {
        resolve(false)
      }
    })

    server.once('listening', () => {
      server.close()
      resolve(false)
    })

    server.listen(port)
  })
}

export default function ViteMockServicePlugin(e: string) {
  return {
    name: 'ViteMockServicePlugin',
    buildStart() {
      ;(async () => {
        const port = 3008
        const portTaken = await isPortTaken(port)
        if (portTaken) {
          console.log(`Port ${port} is already in use`)
        } else {
          if (e === 'mock') {
            // 启动本地 mock 服务（startServer 无需返回值）
            startServer({
              // Path for mock data
              mockDir: join(__dirname, './src/mock'),
              // Configure mock service port to avoid conflicts with application port
              port: 3008,
            })
          }
        }
      })()
    },
  }
}

// vite.config.ts
import { defineConfig } from "vite";
// The vite-mock-plugin imported here is the code snippet above
import ViteMockServicePlugin from "./vite-mock-plugin";

export default defineConfig({ mode })=>{
  return {
    plugins: [ViteMockServicePlugin(mode)],
  }
});

# .env.mock
VITE_SEVER_URL=http://localhost:3008/

// package.json
{
  "scripts": {
    "dev": "vite --mode dev",
    // add mock script
    "mock": "vite --mode mock",
  },
}

Example Projects

• Vue Example
• React Example

Notes

1. Page refresh required after modifying mock data
2. Ensure mock service port doesn't conflict with application port
3. Recommended to use relative paths for mock data directory configuration

Contributing

Issues and Pull Requests are welcome

License

MIT