vite-plugin-automock

Effortless API mock auto-generation for legacy projects. No manual files, just automock!

Features

• Automatically captures API requests and generates local mock data
• Perfect for legacy projects, easily backfill missing mocks
• Supports manual mock file creation with a simple format
• Fine-grained control: enable/disable mock, proxy, and capture independently
• Visual mock inspector panel for managing mock files
• Production-ready with client-side interceptor (Axios / PureHttp)
• Fully compatible with the Vite plugin ecosystem
• Zero-config, plug-and-play

Installation

pnpm add -D vite-plugin-automock
# or
npm install --save-dev vite-plugin-automock
# or
yarn add -D vite-plugin-automock

Quick Start

// vite.config.ts
import { automock } from 'vite-plugin-automock'

export default defineConfig({
  plugins: [
    automock({
      proxyBaseUrl: 'https://api.example.com', // Required for proxy/capture
    })
  ]
})

That's it! The plugin will:

1. Intercept requests matching apiPrefix (default /api)
2. Return mock data if a mock file exists
3. Proxy to proxyBaseUrl and auto-save the response as a mock file

Configuration Options

Plugin Options

| Option | Type | Required | Default | Description | | ------ | ---- | -------- | ------- | ----------- | | proxyBaseUrl | string | No | - | Base URL of your API server. Required only when proxy or capture is used | | mockDir | string | No | 'mock' | Directory to store mock files | | apiPrefix | string | No | '/api' | API path prefix to intercept | | pathRewrite | (path: string) => string | No | (path) => path | Function to rewrite request paths | | enabled | boolean | No | true | Global switch. When false, all requests pass through without mock handling | | proxy | boolean | No | true | Whether to proxy unmatched requests to proxyBaseUrl | | capture | boolean | No | true | Whether to auto-capture proxy responses and save as mock files | | productionMock | boolean \| 'auto' | No | false | Enable client-side mock bundle support | | inspector | boolean \| InspectorOptions | No | false | Enable visual mock inspector UI |

Bundle Options

These options are available when using the automock() function (which includes bundle support):

| Option | Type | Default | Description | | ------ | ---- | ------- | ----------- | | bundleMockData | boolean | true | Whether to bundle mock data for production | | bundleOutputPath | string | 'public/mock-data.json' | Output path for the mock bundle file |

For a complete explanation of option interactions, see Configuration Guide.

Inspector Options

When inspector is an object:

| Option | Type | Default | Description | | ------ | ---- | ------- | ----------- | | route | string | '/__mock/' | Route path for the inspector UI | | enableToggle | boolean | true | Allow toggling mock enable/disable in the UI |

Full Configuration Example

import { automock } from 'vite-plugin-automock'

export default defineConfig({
  plugins: [
    automock({
      // Basic
      proxyBaseUrl: 'https://api.example.com',
      mockDir: 'mock',
      apiPrefix: '/api',
      pathRewrite: (path) => path.replace(/^\/api/, ''),

      // Fine-grained control
      enabled: true,
      proxy: true,
      capture: true,

      // Production
      productionMock: 'auto',
      bundleMockData: true,
      bundleOutputPath: 'public/mock-data.json',

      // Inspector
      inspector: {
        route: '/__mock/',
        enableToggle: true,
      },
    })
  ]
})

Behavior Modes

The enabled, proxy, and capture options control different parts of the development middleware. enabled=false is a global bypass: the plugin will not read mocks, proxy, or capture.

Mock-only Mode

Only return mock data, never proxy to backend. Useful when you want strict offline development:

automock({
  proxyBaseUrl: 'https://api.example.com',
  enabled: true,   // Intercept requests
  proxy: false,    // Don't proxy to backend
  capture: false,  // Don't save new mocks
})

Pass-through Mode

Bypass all automock handling and let later Vite middleware, including server.proxy, handle the request:

automock({
  enabled: false,
})

Default Mode (Recommended)

All features enabled - mock first, proxy fallback, auto-capture:

automock({
  proxyBaseUrl: 'https://api.example.com',
  // enabled: true (default)
  // proxy: true (default)
  // capture: true (default)
})

Client API Reference

The client-side interceptor is used for production mode mock support. Import from vite-plugin-automock/client.

For PureHttp Wrapper

// src/main.ts
import {
  initMockInterceptorForPureHttp,
  setMockEnabled,
  registerHttpInstance
} from 'vite-plugin-automock/client'
import { http } from './http' // Your PureHttp instance

// Register your http instance
registerHttpInstance(http)

// Initialize mock interceptor
initMockInterceptorForPureHttp()
  .then(() => console.log('[MockInterceptor] Initialized'))
  .catch(error => console.error('[MockInterceptor] Failed:', error))

// Enable mock in development
if (import.meta.env.DEV) {
  setMockEnabled(true)
}

For Plain Axios

// src/main.ts
import { initMockInterceptor, setMockEnabled } from 'vite-plugin-automock/client'
import axios from 'axios'

initMockInterceptor(axios)
  .then(() => console.log('[MockInterceptor] Initialized'))
  .catch(error => console.error('[MockInterceptor] Failed:', error))

if (import.meta.env.DEV) {
  setMockEnabled(true)
}

Client Exports

| Export | Type | Description | | ------ | ---- | ----------- | | initMockInterceptor | (axios: AxiosInstance) => Promise<void> | Initialize interceptor with an Axios instance | | initMockInterceptorForPureHttp | () => Promise<void> | Initialize interceptor for PureHttp (call registerHttpInstance first) | | registerHttpInstance | (http: { constructor: { axiosInstance: AxiosInstance } }) => void | Register a PureHttp instance | | setMockEnabled | (enabled: boolean) => void | Enable/disable mock at runtime | | isMockEnabled | () => boolean | Check if mock is currently enabled | | loadMockData | () => Promise<Record<string, MockBundleData>> | Load mock data from the bundled JSON file | | createMockInterceptor | (options: MockInterceptorOptions) => MockInterceptor | Create a custom interceptor instance |

MockInterceptorOptions

interface MockInterceptorOptions {
  mockData: Record<string, MockBundleData>
  enabled?: boolean | (() => boolean)
  onMockHit?: (url: string, method: string, mock: MockBundleData) => void
  onBypass?: (url: string, method: string, reason: string) => void
}

interface MockBundleData {
  enable: boolean
  data: unknown
  delay?: number
  status?: number
  isBinary?: boolean
}

Production Mode

To use mock data in production builds:

1. Enable productionMock and bundleMockData:

automock({
  proxyBaseUrl: 'https://api.example.com',
  productionMock: true,    // or 'auto'
  bundleMockData: true,    // default
  bundleOutputPath: 'public/mock-data.json',
})

2. The plugin will generate public/mock-data.json at build time containing all mock data.

3. Initialize the client interceptor in your app (see Client API Reference).

4. The productionMock: 'auto' option enables mock outside production mode and disables it in production mode.

Mock Inspector

The visual inspector provides a web UI to manage mock files:

automock({
  proxyBaseUrl: 'https://api.example.com',
  inspector: true,  // or { route: '/__mock/', enableToggle: true }
})

Then visit http://localhost:5173/__mock/ to:

• Browse all mock files organized by URL
• Toggle mock enable/disable status
• Adjust response delay and status codes
• Edit JSON response data directly
• Create new mock files
• Delete existing mock files
• Batch update multiple mocks at once

Mock File Structure

Mock files are organized by URL path and HTTP method:

mock/
├── api/
│   ├── users/
│   │   ├── get.js     # GET /api/users
│   │   └── post.js    # POST /api/users
│   └── items/
│       ├── get.js     # GET /api/items
│       └── post.js    # POST /api/items

Each mock file exports an object:

/**
 * Mock data for /api/users (GET)
 * Generated at 2025-01-11T10:30:00.000Z
 */
export default {
  enable: false,   // Whether to use this mock
  data: {
    code: 0,
    message: "success",
    data: [
      { id: 1, name: "User 1" },
      { id: 2, name: "User 2" },
    ],
  },
  delay: 0,    // Artificial delay in milliseconds
  status: 200, // HTTP status code
}

Dynamic Mock Data

export default {
  enable: true,
  data: () => ({
    timestamp: new Date().toISOString(),
    randomId: Math.floor(Math.random() * 1000),
  }),
}

Common Pitfalls

Dual Proxy Configuration

Do NOT configure both Vite's server.proxy and automock's proxyBaseUrl for the same API prefix:

// ❌ Wrong - will cause request conflicts
export default defineConfig({
  plugins: [
    automock({ proxyBaseUrl: 'http://localhost:8888', apiPrefix: '/api' })
  ],
  server: {
    proxy: {
      '/api': { target: 'http://localhost:8888', changeOrigin: true } // CONFLICTS
    }
  }
})

// ✅ Correct - use automock for /api, remove server.proxy
export default defineConfig({
  plugins: [
    automock({ proxyBaseUrl: 'http://localhost:8888', apiPrefix: '/api' })
  ]
})

The plugin will automatically warn you if a conflicting proxy is detected.

How It Works

1. Request Interception: The plugin intercepts all requests matching apiPrefix
2. Mock Check: Checks if a corresponding mock file exists and is enabled
3. Conditional Response:
   • Mock exists and enabled -> Returns mock data
   • Mock exists but disabled -> Skips to proxy or next middleware
   • Mock doesn't exist -> Proxies to real API (if proxy: true)
4. Auto-Capture: Real API responses are automatically saved as mock files (if capture: true)
5. Hot Reloading: Changes to mock files are automatically detected and reloaded
6. Bundle: Mock data is bundled into JSON for production use

Comparison with Traditional Mock Plugins

| Feature | Traditional Mock Plugins | vite-plugin-automock | | ------- | ----------------------- | -------------------- | | Auto backfill | - | Yes | | Legacy project support | - | Yes | | Manual mock files | Yes | Yes | | Config complexity | High | Very low | | Zero setup | - | Yes | | Real API integration | - | Yes | | Fine-grained control | - | Yes | | Visual inspector | - | Yes | | Production mock | - | Yes |

When to Use

• Legacy Projects: Quickly add mock capability to existing projects
• API Development: Test frontend while backend is being developed
• Offline Development: Work without internet or when APIs are unavailable
• Testing: Consistent test data without external dependencies
• Demo/Presentation: Reliable demo data that doesn't change

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

ISC