Config

CLI Options

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

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

-m, --mocks-dir <dir>  (default: ./mockaton-mocks/)
-s, --static-dir <dir> (default: ./mockaton-static-mocks/)

-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

-h, --help
-v, --version

mockaton.config.js (Optional)

Mockaton looks for a file mockaton.config.js in its current working directory. The next section has the documentation, but here’s an overview of the defaults: 

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

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

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

  logLevel: 'normal',

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

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

Config Documentation

mocksDir?: string

Defaults to mockaton-mocks in the current working directory.

staticDir?: string

Defaults to mockaton-static-mocks in the current working directory.

This option is not needed besides serving partial content (e.g., videos). But it’s convenient for serving 200 GET requests without having to add the filename extension convention. For example, for using Mockaton as a standalone demo server.

Files under config.staticDir take precedence over corresponding GET mocks in config.mocksDir (regardless of status code). For example, if you have two files for GET /foo/bar.jpg such as: 

my-static-dir/foo/bar.jpg  // Wins
 my-mocks-dir/foo/bar.jpg.GET.200.jpg  // Unreachable

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.


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.com’

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'