vite-plugin-automock 1.1.5 → 1.2.0

package/README.md

@@ -6,13 +6,14 @@ Effortless API mock auto-generation for legacy projects. No manual files, just a
 
 ## 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
-- ⚡ Zero-config, plug-and-play
-- 🧩 Fully compatible with the Vite plugin ecosystem
-- 📦 Production-ready with client-side interceptor
-- 🎛️ Visual mock inspector panel
+- 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
 
@@ -26,8 +27,6 @@ yarn add -D vite-plugin-automock
 
 ## Quick Start
 
-### 1. Configure Vite Plugin
-
 ```typescript
 // vite.config.ts
 import { automock } from 'vite-plugin-automock'
@@ -35,36 +34,136 @@ 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](docs/CONFIGURATION_CN.md).
+
+### 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
+
+```typescript
+import { automock } from 'vite-plugin-automock'
+
+export default defineConfig({
+  plugins: [
+    automock({
+      // Basic
+      proxyBaseUrl: 'https://api.example.com',
       mockDir: 'mock',
       apiPrefix: '/api',
-      bundleMockData: true,      // Bundle mock data for production
-      productionMock: true,       // Enable mock in production
-      proxyBaseUrl: 'https://api.example.com'
+      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,
+      },
     })
   ]
 })
 ```
 
-### 2. Create Mock Files
+## 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:
 
 ```typescript
-// mock/users.ts
-import { MockFileConfig } from 'vite-plugin-automock'
+automock({
+  proxyBaseUrl: 'https://api.example.com',
+  enabled: true,   // Intercept requests
+  proxy: false,    // Don't proxy to backend
+  capture: false,  // Don't save new mocks
+})
+```
 
-export default {
-  enable: true,
-  data: { users: [{ id: 1, name: 'Alice' }] },
-  delay: 100,
-  status: 200
-} as MockFileConfig
+### Pass-through Mode
+
+Bypass all automock handling and let later Vite middleware, including `server.proxy`, handle the request:
+
+```typescript
+automock({
+  enabled: false,
+})
+```
+
+### Default Mode (Recommended)
+
+All features enabled - mock first, proxy fallback, auto-capture:
+
+```typescript
+automock({
+  proxyBaseUrl: 'https://api.example.com',
+  // enabled: true (default)
+  // proxy: true (default)
+  // capture: true (default)
+})
 ```
 
-### 3. Initialize Client Interceptor
+## Client API Reference
 
-For PureHttp wrapper:
+The client-side interceptor is used for **production mode** mock support. Import from `vite-plugin-automock/client`.
+
+### For PureHttp Wrapper
 
 ```typescript
-// src/main.ts or src/api/index.ts
+// src/main.ts
 import {
   initMockInterceptorForPureHttp,
   setMockEnabled,
@@ -77,12 +176,8 @@ registerHttpInstance(http)
 
 // Initialize mock interceptor
 initMockInterceptorForPureHttp()
-  .then(() => {
-    console.log('[MockInterceptor] Initialized successfully')
-  })
-  .catch(error => {
-    console.error('[MockInterceptor] Failed to initialize:', error)
-  })
+  .then(() => console.log('[MockInterceptor] Initialized'))
+  .catch(error => console.error('[MockInterceptor] Failed:', error))
 
 // Enable mock in development
 if (import.meta.env.DEV) {
@@ -90,167 +185,94 @@ if (import.meta.env.DEV) {
 }
 ```
 
-For plain Axios:
+### For Plain Axios
 
 ```typescript
 // src/main.ts
 import { initMockInterceptor, setMockEnabled } from 'vite-plugin-automock/client'
 import axios from 'axios'
 
-// Initialize with axios instance
 initMockInterceptor(axios)
-  .then(() => {
-    console.log('[MockInterceptor] Initialized successfully')
-  })
-  .catch(error => {
-    console.error('[MockInterceptor] Failed to initialize:', error)
-  })
+  .then(() => console.log('[MockInterceptor] Initialized'))
+  .catch(error => console.error('[MockInterceptor] Failed:', error))
 
-// Enable mock in development
 if (import.meta.env.DEV) {
   setMockEnabled(true)
 }
 ```
 
-## Documentation
-
-For detailed usage instructions, configuration options, and examples, see:
-
-**[📚 Complete Usage Guide](./docs/USAGE_GUIDE.md)**
-
-Topics covered:
-- Development vs Production modes
-- Client interceptor configuration
-- Runtime mock toggle
-- Visual inspector
-- API reference
-- Common scenarios
-
----
-
-## Basic Usage (Development Mode)
+### Client Exports
 
-Import and register the plugin in your `vite.config.ts`:
+| 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 |
 
-```js
-import { automock } from "vite-plugin-automock";
+### MockInterceptorOptions
 
-export default {
-  plugins: [
-    automock({
-      proxyBaseUrl: "http://localhost:8888", // Required: Your API server URL
-      mockDir: "mock", // Optional: Directory for mock files (default: 'mock')
-      apiPrefix: "/api", // Optional: API prefix to intercept (default: '/api')
-      pathRewrite: (path) => path, // Optional: Path rewrite function
-      inspector: true, // Optional: Enable visual inspector (default: false)
-    }),
-  ],
-};
-```
-
-### With Custom Inspector Configuration
+```typescript
+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
+}
 
-```js
-automock({
-  proxyBaseUrl: "http://localhost:8888",
-  inspector: {
-    route: "/__inspector/", // Custom route for inspector UI
-    enableToggle: true, // Allow toggling enable/disable
-  },
-});
+interface MockBundleData {
+  enable: boolean
+  data: unknown
+  delay?: number
+  status?: number
+  isBinary?: boolean
+}
 ```
 
-## Configuration Options
+## Production Mode
 
-| Option         | Type              | Required | Default          | Description                       |
-| -------------- | ----------------- | -------- | ---------------- | --------------------------------- |
-| `proxyBaseUrl` | string            | ✅       | -                | Base URL of your API server       |
-| `mockDir`      | string            | ❌       | `'mock'`         | Directory to store mock files     |
-| `apiPrefix`    | string            | ❌       | `'/api'`         | API path prefix to intercept      |
-| `pathRewrite`  | function          | ❌       | `(path) => path` | Function to rewrite request paths |
-| `inspector`    | boolean \| object | ❌       | `false`          | Enable visual mock inspector UI   |
+To use mock data in production builds:
 
-## Common Pitfalls
-
-### ⚠️ Dual Proxy Configuration
-
-**Do NOT** configure both Vite's `server.proxy` and automock's `proxyBaseUrl` for the same API prefix. This will cause conflicts and requests may hang.
-
-**❌ Wrong:**
-```typescript
-export default defineConfig({
-  plugins: [
-    automock({
-      proxyBaseUrl: "http://localhost:8888",
-      apiPrefix: "/api",
-    })
-  ],
-  server: {
-    proxy: {
-      "/api": {  // ❌ CONFLICTS with automock
-        target: "http://localhost:8888",
-        changeOrigin: true,
-      }
-    }
-  }
-})
-```
+1. Enable `productionMock` and `bundleMockData`:
 
-**✅ Correct:**
 ```typescript
-export default defineConfig({
-  plugins: [
-    automock({
-      proxyBaseUrl: "http://localhost:8888",
-      apiPrefix: "/api",
-    })
-  ],
-  // ✅ Remove server.proxy or use a different prefix
+automock({
+  proxyBaseUrl: 'https://api.example.com',
+  productionMock: true,    // or 'auto'
+  bundleMockData: true,    // default
+  bundleOutputPath: 'public/mock-data.json',
 })
 ```
 
-The plugin will automatically warn you if a conflicting proxy configuration is detected.
+2. The plugin will generate `public/mock-data.json` at build time containing all mock data.
 
-### Inspector Options
+3. Initialize the client interceptor in your app (see [Client API Reference](#client-api-reference)).
 
-When `inspector` is an object, you can customize:
+4. The `productionMock: 'auto'` option enables mock outside `production` mode and disables it in `production` mode.
 
-| Option         | Type    | Default      | Description                        |
-| -------------- | ------- | ------------ | ---------------------------------- |
-| `route`        | string  | `'/__mock/'` | Route path for the inspector UI    |
-| `enableToggle` | boolean | `true`       | Allow toggling mock enable/disable |
+## Mock Inspector
 
-## Mock Inspector 🎨
+The visual inspector provides a web UI to manage mock files:
 
-**NEW!** Visual interface to manage your mock files:
-
-```js
+```typescript
 automock({
-  proxyBaseUrl: "http://localhost:8888",
-  inspector: true, // Enable inspector UI
-});
+  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
-- 💾 **Save** changes with a single click
-
-![Inspector Demo](https://via.placeholder.com/800x400?text=Mock+Inspector+UI)
-
-## How It Works
-
-1. **Request Interception**: The plugin intercepts all requests matching the `apiPrefix`
-2. **Mock Check**: Checks if a corresponding mock file exists
-3. **Conditional Response**:
-   - If mock exists → Returns mock data
-   - If mock doesn't exist → Proxies to real API and saves response as mock
-4. **Auto-Generation**: Real API responses are automatically saved as mock files
-5. **Hot Reloading**: Changes to mock files are automatically detected and reloaded
-6. **Visual Inspector**: Manage and edit mocks through the web UI
+- **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
 
@@ -267,7 +289,7 @@ mock/
 │       └── post.js    # POST /api/items
 ```
 
-Each mock file exports an object with this structure:
+Each mock file exports an object:
 
 ```javascript
 /**
@@ -275,9 +297,8 @@ Each mock file exports an object with this structure:
  * Generated at 2025-01-11T10:30:00.000Z
  */
 export default {
-  enable: false, // Whether to use this mock (default: false)
+  enable: false,   // Whether to use this mock
   data: {
-    // Response data
     code: 0,
     message: "success",
     data: [
@@ -285,55 +306,77 @@ export default {
       { id: 2, name: "User 2" },
     ],
   },
-  delay: 0, // Artificial delay in milliseconds
+  delay: 0,    // Artificial delay in milliseconds
   status: 200, // HTTP status code
-};
+}
 ```
 
-## Quick Start
+### Dynamic Mock Data
 
-1. **Try the Example**:
+```javascript
+export default {
+  enable: true,
+  data: () => ({
+    timestamp: new Date().toISOString(),
+    randomId: Math.floor(Math.random() * 1000),
+  }),
+}
+```
 
-   ```bash
-   pnpm run example
-   ```
+## Common Pitfalls
 
-   This starts the playground with a demo API server.
+### Dual Proxy Configuration
 
-2. **Manual Setup**:
+**Do NOT** configure both Vite's `server.proxy` and automock's `proxyBaseUrl` for the same API prefix:
+
+```typescript
+// ❌ 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
+    }
+  }
+})
 
-   ```bash
-   # Install the plugin
-   pnpm add -D vite-plugin-automock
+// ✅ Correct - use automock for /api, remove server.proxy
+export default defineConfig({
+  plugins: [
+    automock({ proxyBaseUrl: 'http://localhost:8888', apiPrefix: '/api' })
+  ]
+})
+```
 
-   # Add to your vite.config.js
-   import { automock } from "vite-plugin-automock";
+The plugin will automatically warn you if a conflicting proxy is detected.
 
-   export default {
-     plugins: [
-       automock({
-         proxyBaseUrl: "http://localhost:8888"
-       })
-     ]
-   };
-   ```
+## How It Works
 
-3. **Start Development**:
-   - Start your API server
-   - Start Vite dev server
-   - Make API calls from your frontend
-   - Check the mock directory for generated files
+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          | ❌                       | ✅                   |
-| Legacy project support | ❌                       | ✅                   |
-| Manual mock files      | ✅                       | ✅                   |
-| Config complexity      | High                     | Very low             |
-| Zero setup             | ❌                       | ✅                   |
-| Real API integration   | ❌                       | ✅                   |
+| 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
 
@@ -343,45 +386,6 @@ export default {
 - **Testing**: Consistent test data without external dependencies
 - **Demo/Presentation**: Reliable demo data that doesn't change
 
-## Advanced Usage
-
-### Custom Path Rewriting
-
-```javascript
-automock({
-  proxyBaseUrl: "http://api.example.com",
-  pathRewrite: (path) => {
-    // Remove /api prefix when proxying
-    return path.replace(/^\/api/, "");
-  },
-});
-```
-
-### Conditional Mock Enabling
-
-```javascript
-// In your mock file
-export default {
-  enable: process.env.NODE_ENV === "development",
-  data: {
-    /* mock data */
-  },
-};
-```
-
-### Dynamic Mock Data
-
-```javascript
-// In your mock file
-export default {
-  enable: true,
-  data: () => ({
-    timestamp: new Date().toISOString(),
-    randomId: Math.floor(Math.random() * 1000),
-  }),
-};
-```
-
 ## Contributing
 
 We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.