v13.9.3

Config

CLI Options

The CLI options override their counterparts in mockaton.config.js

mockaton [mocks-dir] [options]

[mocks-dir]          (default: ./mockaton-mocks/)

-c, --config <file>  (default: ./mockaton.config.js)

-H, --host <host>    (default: 127.0.0.1)
-p, --port <port>    (default: 0) which means auto-assigned

-q, --quiet          Errors only
--no-open            Don’t open dashboard in a browser
--no-read-only       Allow writing and deleting mocks via API

--skills             Show AI agent SKILLS.md file path
-h, --help
-v, --version

mockaton.config.js (Optional)

Mockaton looks for a file mockaton.config.js in its current working directory. Here’s an overview of the defaults: 

import { 
  defineConfig, 
  jsToJsonPlugin, 
  openInBrowser, 
  SUPPORTED_METHODS 
} from 'mockaton'

export default defineConfig({
  mocksDir: 'mockaton-mocks',
  ignore: /(\.DS_Store|~)$/,
  watcherEnabled: true,
  watcherDebounceMs: 80,

  host: '127.0.0.1',
  port: 0, // auto-assigned

  logLevel: 'normal',

  delay: 1200, // ms. Applies to routes with the Delay Checkbox "ON"
  delayJitter: 0, // 0 to 3 float percent

  proxyFallback: '',
  collectProxied: false,
  formatCollectedJSON: true,

  cookies: {},
  extraHeaders: [],
  extraMimes: {},

  corsAllowed: true,
  corsOrigins: ['*'],
  corsMethods: SUPPORTED_METHODS,
  corsHeaders: ['content-type', 'authorization'],
  corsExposedHeaders: [],
  corsCredentials: true,
  corsMaxAge: 0,

  plugins: [
    [/\.(js|ts)$/, jsToJsonPlugin]
  ],

  onReady: await openInBrowser
})

mocksDir?: string

Defaults to mockaton-mocks in the current working directory.

This directory contains your mocks. Files that don’t follow the Filename Convention are served as GET 200 or GET 206 (partial content, e.g., for videos).

ignore?: RegExp

Defaults to /(\.DS_Store|~)$/

The regex rule is tested against the basename (filename without a directory path).

watcherEnabled?: boolean

Defaults to true

When false, if you add, delete, or rename you’ll need to click "Reset" on the Dashboard, or call commander.reset() in order to re-initialize the collection.

On the other hand, edits are not affected by this flag; mocks are always read from disk on every request.

watcherDebounceMs?: number

Defaults to 80ms

Slight delay for registering and unregistering mocks. For instance, so renaming a mock emits only once (not twice for "write" and "remove").


host?: string

Defaults to 127.0.0.1

port?: number

Defaults to 0, which means auto-assigned


delay?: number

Defaults to 1200 milliseconds. Although routes can individually be delayed with the 🕓 Checkbox, the amount is globally configurable with this option.

delayJitter?: number

Defaults to 0. Range: [0.0, 3.0]. Maximum percentage of the delay to add. For example, 0.5 will add at most 600ms to the default delay.


proxyFallback?: string

For example, config.proxyFallback = ’http://example.test

Lets you specify a target server for serving routes you don’t have mocks for, or that you manually picked with the ☁️ Cloud Checkbox.

collectProxied?: boolean

Defaults to false. With this flag you can save mocks that hit your proxy fallback to config.mocksDir. If the URL has v4 UUIDs, the filename will have [id] in their place. For example: 

/api/user/d14e09c8-d970-4b07-be42-b2f4ee22f0a6/likes =>
  my-mocks-dir/api/user/[id]/likes.GET.200.json

Your existing mocks won’t be overwritten. Responses of routes with the ☁️ Cloud Checkbox selected will be saved with unique filename-comments.

An .empty extension means the Content-Type header was not sent by your backend.

An .unknown extension means the Content-Type is not in the predefined list. For that, you can add it to config.extraMimes

formatCollectedJSON?: boolean

Defaults to true. Saves the mock with two spaces indentation — the formatting output of JSON.stringify(data, null, ’ ’)

cookies?: { [label: string]: string } 

import { jwtCookie } from 'mockaton'

config.cookies = {
  'My Admin User': 'my-cookie=1;Path=/;SameSite=strict',
  'My Normal User': 'my-cookie=0;Path=/;SameSite=strict',
  'My JWT': jwtCookie('my-cookie', {
    name: 'John Doe',
    picture: 'https://cdn.auth0.com/avatars/jd.png'
  }),
  'None': ''
}

The selected cookie, which is the first one by default, is sent in every response in a Set-Cookie header (as long as its value is not an empty string). The object key is just a label for UI display purposes and also for selecting a cookie via the Commander API.

If you need to send more than one cookie, you can inject them globally in config.extraHeaders, or individually in a function .js or .ts mock.

By the way, the jwtCookie helper has a hardcoded header and signature. So it’s useful only if you care about its payload.

extraHeaders?: string[]

Note: it’s a one-dimensional array. The header name goes at even indices. 

config.extraHeaders = [
  'Server', 'Mockaton',
  'Set-Cookie', 'foo=FOO;Path=/;SameSite=strict',
  'Set-Cookie', 'bar=BAR;Path=/;SameSite=strict'
]

extraMimes?: { [fileExt: string]: string } 

config.extraMimes = {
  jpe: 'application/jpeg',
  html: 'text/html; charset=utf-8' // overrides built-in
}

Those extra media types take precedence over the built-in utils/mime.js, so you can override them.

plugins?: [filenameTester: RegExp, plugin: Plugin][]

See Plugins Page

corsAllowed?: boolean

Defaults to true. When true, these are the default options: 

config.corsOrigins = ['*']
config.corsMethods = require('node:http').METHODS
config.corsHeaders = ['content-type', 'authorization']
config.corsCredentials = true
config.corsMaxAge = 0 // seconds to cache the preflight req
config.corsExposedHeaders = [] // headers you need to access in client-side JS

onReady?: (dashboardUrl: string) => void

By default, it will open the dashboard in your default browser on macOS and Windows. But for a more cross-platform utility you could npm install open and that implementation will be automatically used instead.

If you don’t want to open a browser, pass a noop:

config.onReady = () => {}

At any rate, you can trigger any command besides opening a browser.


logLevel?: 'quiet' | 'normal' | 'verbose'

Defaults to 'normal'