mock.config.js

All fields are optional. This shows every default:

module.exports = {
  dir: 'mock',                  // where mock/api and mock/data live, relative to cwd
  seed: 'mockingpug',            // deterministic generation seed
  baseUrl: '/api',               // used by mockingpug/react and mockingpug/next
  persist: {
    adapter: 'file',             // 'file' | 'memory'
    strategy: 'always',          // 'always' (reconcile) | 'fresh' (regenerate every run)
  },
  pagination: {
    strategy: 'page',            // 'page' | 'offset' | 'cursor' | false
    params: { page: 'page', limit: 'limit', offset: 'offset', cursor: 'cursor', groupBy: 'groupBy', limitPerGroup: 'limitPerGroup' },
    defaultLimit: 20,
    maxLimit: 100,
    envelope: true,               // true -> { data, meta } body; false -> raw array + X-* headers
  },
  limits: {
    maxAmount: 100_000,           // doctor warns (fails with --strict) above this per-entity `amount`
    maxArrayDepth: 3,             // doctor warns (fails with --strict) above this array[type].N
  },
  runtime: {
    errorRate: 0,                 // [0,1] fraction of requests synthetically failing with a 500
    delay: 0,                     // artificial latency (ms) added to every mock response
  },
  docs: {
    enabled: true,                 // mpug docs + <MockDevtools>'s "API Docs" button
  },
  // response: {                    // optional: wrap list/one/mutation/composite/action bodies
  //   envelope: { data: '$payload', meta: '$meta', errors: [] },
  //   listKey: 'items',            // nests a list under data.items
  // },
  // target: 'https://api.example.com', // mockingpug/next only, no default — needed for <MockDevtools>'s per-request bypass
};

CommonJS (module.exports) works out of the box regardless of your project's own module type, since mockingpug loads this file via a plain dynamic import() and Node's CJS/ESM interop handles the rest. An ESM export default {...} also works if your project has "type": "module".

Field reference

`dir`

Path to the folder holding api/ and data/ subfolders, relative to process.cwd(). Change this if your schemas live somewhere other than mock/. For example, CRA projects typically need src/mock (see the React guide).

`seed`

Any string or number. Every generated value is a pure function of (seed, entity, index, fieldName): changing the seed reshuffles the entire dataset; keeping it fixed reproduces the exact same dataset on any machine.

`baseUrl`

The path prefix mockingpug/react and mockingpug/next mount entities under, e.g. /api/user for entity user with the default /api.

`persist.adapter`

'file': .mockingpug/db/<entity>.json. Default for the CLI and mockingpug/next.
'memory': nothing survives the process. The only sensible choice for mockingpug/react in a browser (there's no filesystem to write to), and useful anywhere you don't want .mockingpug/db written to disk at all.

`persist.strategy`

'always': reconcile (see Reconciliation & Storage).
'fresh': wipe and fully regenerate on every run.

`pagination.*`

See Pagination for the full breakdown of strategies, query param naming, and the envelope option.

`limits.maxAmount` / `limits.maxArrayDepth`

Guardrails checked by mpug doctor (not enforced at generation time itself). A schema with an amount or array[type].N above these values produces a warning (a hard failure under --strict). This exists both as a performance sanity check and as a DoS-guard: a schema merged from an untrusted PR shouldn't be able to silently blow up CI's memory or runtime.

`runtime.errorRate` / `runtime.delay`

Synthetic latency/failure injection, applied identically by mockingpug/react and mockingpug/next at the start of every request:

delay (ms): awaited before any real work happens.
errorRate ([0, 1]): the probability that a request throws an unexpected error instead of resolving, which surfaces to the client as a generic 500 (the same path a genuine internal failure takes, not a RequestError, since this is meant to simulate a real backend failure for testing your app's error-handling UI).

Both default to 0 (disabled). Edit them live without a restart via <MockDevtools> if you're using it.

errorRate lives on the server process (ctx.runtime), not in the browser, so setting it to 1 in mockingpug/next's <MockDevtools> can lock you out of the very page that renders the panel: if the page does any server-side data fetching and your app has no error boundary around it, the whole route fails to render, <MockDevtools> never mounts, and there's no UI left to dial errorRate back down. This isn't the panel itself being blocked — every devtools sub-API call is a guaranteed exception to errorRate/delay, covered by a regression test — it's the host page crashing around it. If this happens, you don't have to restart the dev server: append ?mpug-bypass=1 to the failing request's URL (or send an X-Mockingpug-Bypass: 1 header, for requests you don't control the URL of), and that one request skips errorRate/delay — and any armed one-shot override — entirely, checked before anything else. It's a per-request escape hatch, not a config change: it doesn't touch ctx.runtime or consume an armed override, so everything else keeps behaving exactly as configured. Restarting the dev server (or redeploying) still works too — ctx.runtime is in-memory only, so the next process start reloads errorRate: 0 (or whatever mock.config.js sets) from scratch; nothing is corrupted or persisted. This doesn't affect mockingpug/react: the panel lives entirely client-side there, so it keeps rendering regardless of errorRate. For testing one specific error/loading state without this risk at all, prefer the panel's per-entity one-shot "Fail next request"/"Delay next" override over the global errorRate/delay — see Devtools.

`docs.enabled`

Controls both npx mpug docs (writes nothing and reports itself disabled when false, instead of generating .mockingpug/docs/{openapi.json, index.html}) and whether <MockDevtools> shows its "API Docs" button at all. Defaults to true. Set to false if you'd rather not have an auto-generated description of your mock's exact shape sitting around, or if you already publish your own API docs and don't want a second, generated one. See Devtools for what the button does.

`target`

Base URL of a real backend, e.g. 'https://api.example.com' (no trailing slash) — mockingpug/next only. No default: unset means <MockDevtools>'s per-request "Use real data" switch stays hidden for that transport, since there's nowhere to forward a bypassed request's requests to. mockingpug/react doesn't need this — MSW's passthrough() already knows the real absolute URL the browser's own fetch() used. See Devtools → per-request bypass for Next.js.

`response.*`

Optional response-envelope template, applied to list/one/mutation/ composite/action responses so the mock matches a backend's exact body shape. response.envelope is a template object where "$payload" is replaced by the result and "$meta" by the pagination meta (any other value passes through literally); response.listKey nests a list under that key inside $payload. Unset → the plain { data, meta } / raw-array shape from pagination.envelope. See Endpoints → Response envelope.

mock.config.js

On this page