@mockingbirdjs/next

Next.js 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/next msw

Setup

1. Wrap your Next.js config

// next.config.js
import { withMockingbird } from "@mockingbirdjs/next";

export default withMockingbird({ dir: "mockingbird" })({
  // your existing Next.js config
});

2. Add the provider to your root layout

// app/layout.tsx
import { MockingbirdProvider } from "@mockingbirdjs/next/client";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {process.env.NODE_ENV === "development" ? (
          <MockingbirdProvider config={{ mode: "hybrid", backends: [], include: ["/api/**"], ignore: [], routes: [] }}>
            {children}
          </MockingbirdProvider>
        ) : (
          children
        )}
      </body>
    </html>
  );
}

Run next dev, browse your app. Fixtures accumulate in mockingbird/fixtures/.

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 (press alt+m) or @mockingbirdjs/cli.

Options

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

  // Starting mode. Default: 'hybrid'
  mode: "hybrid",

  // Port for the Mockingbird sidecar HTTP server. Default: 54321
  port: 54321,

  // 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,
    hotkey: "alt+m",
    position: "bottom-right",  // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  },

  // Recording behaviour
  record: {
    maxBodyBytes: 5_000_000,
    maxVariantsPerEndpoint: 10,
    onDuplicate: "update",  // 'update' | 'keep' | 'variants'
    latency: true,
    wildcardFallback: true,
  },

  // 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,
})

CLI

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

See @mockingbirdjs/cli for details.