@mockingbirdjs/vite

Vite plugin for Mockingbird — record your real backend once, develop locally forever.

Browse your app while the backend is up; Mockingbird records every request into readable JSON fixtures. Kill the backend, keep working. Edit a fixture, save, the app reflects it instantly — zero MSW boilerplate.

Install

npm i -D @mockingbirdjs/vite msw

Setup

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { mockingbird } from "@mockingbirdjs/vite";

export default defineConfig({
  plugins: [react(), mockingbird()],
});

Run vite, click through your app once. Fixtures appear in mockingbird/fixtures/. The overlay in the corner (press alt+m) shows live hit/miss/record status.

Modes

| Mode | Behaviour | Default | |---|---|:---:| | hybrid | Serves fixtures when known, records when not | ✓ | | live | Always hits the real backend, always records | | | mock | Never hits the backend — 501 on unknown routes | |

Switch at runtime with the overlay or the @mockingbirdjs/cli.

Options

mockingbird({
  // Fixture directory relative to Vite root. Default: 'mockingbird'
  dir: "mockingbird",

  // Starting mode (overlay/CLI overrides this at runtime). Default: 'hybrid'
  mode: "hybrid",

  // Cross-origin API bases to intercept. Default: []
  backends: ["https://api.staging.acme.dev"],

  // Path globs to intercept. Default: ['**']
  include: ["/api/**"],

  // Path globs never intercepted. Default: []
  ignore: ["/api/analytics/**"],

  // Overlay. false disables it entirely.
  overlay: {
    defaultOpen: false,     // start drawer open
    hotkey: "alt+m",        // toggle shortcut
    position: "bottom-right",
  },

  // Recording behaviour
  record: {
    maxBodyBytes: 5_000_000,        // bodies larger than this become stubs
    maxVariantsPerEndpoint: 10,     // max fixtures per route
    onDuplicate: "update",          // 'update' | 'keep' | 'variants'
    latency: true,                  // capture response time
    wildcardFallback: true,         // write a wildcard fixture for parameterised routes
  },

  // Replay behaviour
  replay: {
    latency: "none",  // 'none' | 'recorded' | ms | { min, max }
  },

  // Per-route overrides — first match wins
  routes: [
    { pattern: "GET /api/flags", mode: "live" },
    { pattern: "/api/analytics/**", ignore: true },
  ],

  // Secret scrubbing before anything hits disk
  sanitize: {
    bodyPaths: ["**.password", "**.token"],
    headers: ["set-cookie", "authorization"],
    queryParams: ["token", "key"],
  },

  // Last-chance hook before a recording hits disk. Return null to drop.
  onRecord: (exchange) => exchange,
})

Client import

The browser client is available at the /client subpath for advanced use:

import { createMockingbird } from "@mockingbirdjs/vite/client";

CLI

npx mockingbird status
npx mockingbird mode mock
npx mockingbird list
npx mockingbird sanitize --check

See @mockingbirdjs/cli for details.