mock-service-plugin weekly downloads statistics

mock-service-plugin

English | 中文

A powerful local Mock service plugin that supports Webpack, Vite, and other mainstream build tools — letting you develop and debug frontend pages even before the backend APIs are ready.

Table of Contents

• What is Mocking?
• Features
• Installation
• 5-Minute Quick Start
• Mock File Specification
• MockJS Syntax Reference
• Supported File Formats
• Full Format Examples
• Advanced Features
• Framework Integration
• Debug Interface
• FAQ
• Example Projects

---

What is Mocking?

In real-world development, frontend and backend teams often work in parallel. When the backend APIs aren't ready yet, the frontend has no data to work with and development stalls.

Mocking means running a fake backend service locally that returns dummy data according to the agreed API contract, so frontend development can proceed independently without relying on a real backend.

What mock-service-plugin does is: read your mock data files, automatically start a local HTTP server, and return the corresponding data when frontend requests come in.

---

Features

• 🚀 Supports multiple build tools: Webpack 4/5, Vite, Vue CLI, Create React App
• 🎯 Compatible with Vue, React, and other mainstream frameworks
• 🔥 Feature-rich
  • RESTful API support (GET / POST / PUT / DELETE, etc.)
  • Dynamic route parameters (e.g. /api/users/:id)
  • Streaming responses (SSE / EventStream, simulates AI typewriter effect)
  • Multiple response formats (JSON / XML / CSV / Image / Plain text, etc.)
• 💡 Minimal configuration, hot reload, built-in debug interface

---

Installation

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

# yarn
yarn add mock-service-plugin --dev

# pnpm
pnpm add mock-service-plugin --save-dev

---

5-Minute Quick Start

The following uses a Vite + Vue project as an example to walk you through your first Mock API from scratch.

Step 1: Install the Plugin

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

Step 2: Create the Mock Directory and File

Create a mocks folder in the project root and add a file mocks/user.json:

project-root/
├── mocks/
│   └── user.json   ← create this file
├── src/
├── vite.config.ts
└── package.json

Contents of mocks/user.json:

/**
 * @url /api/user/info
 * @method GET
 */
{
  "code": 200,
  "data": {
    "id": "@id",
    "name": "@cname",
    "email": "@email",
    "avatar": "@image('100x100')"
  },
  "message": "success"
}

The /** ... */ comment at the top is the route configuration, telling the plugin which API path and HTTP method this file corresponds to.
@cname, @email, etc. are MockJS random data placeholders — each request generates different random data. See MockJS Syntax Reference for full syntax.

Step 3: Start the Mock Service in Vite

Create vite-mock-plugin.ts in the project root:

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

// Check if a port is already in use
function isPortTaken(port: number): Promise<boolean> {
  return new Promise((resolve) => {
    const server = createServer();
    server.once("error", (err: { code: string }) => {
      resolve(err.code === "EADDRINUSE");
    });
    server.once("listening", () => {
      server.close();
      resolve(false);
    });
    server.listen(port);
  });
}

// Vite plugin: start Mock service in mock mode
export default function ViteMockServicePlugin(mode: string) {
  return {
    name: "ViteMockServicePlugin",
    buildStart() {
      (async () => {
        const port = 3008;
        if (await isPortTaken(port)) {
          console.log(`[Mock] Port ${port} is already in use, skipping start`);
          return;
        }
        if (mode === "mock") {
          startServer({
            mockDir: join(__dirname, "./mocks"), // path to mock folder
            port, // mock service port
          });
        }
      })();
    },
  };
}

Update vite.config.ts:

// vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import ViteMockServicePlugin from "./vite-mock-plugin";

export default defineConfig(({ mode }) => ({
  plugins: [
    vue(),
    ViteMockServicePlugin(mode), // pass current mode
  ],
  server: {
    proxy: {
      // Proxy /api requests to the mock service
      "/api": {
        target: "http://localhost:3008",
        changeOrigin: true,
      },
    },
  },
}));

Add a mock start script to package.json:

{
  "scripts": {
    "dev": "vite --mode dev",
    "mock": "vite --mode mock"
  }
}

Step 4: Start and Test

npm run mock

After starting, open http://localhost:3008/api/user/info in your browser and you'll see randomly generated user data:

{
  "code": 200,
  "data": {
    "id": "660000198812040277",
    "name": "Han Lei",
    "email": "c.wjjdmpyy@wfomlb.net",
    "avatar": "http://dummyimage.com/100x100"
  },
  "message": "success"
}

Congratulations! You've successfully set up your first Mock API. 🎉

---

Mock File Specification

File Structure

Each mock file consists of two parts:

file = top comment (route config) + response body

/**
 * @url /api/users        ← required: API path
 * @method GET            ← optional: HTTP method, defaults to GET
 */
{
  "code": 200,
  "data": []
}

Annotation Reference…