Options
How to define options
There are multiple methods for defining Mocks Server configuration:
Read the previous chapter for further info about how to define configuration using different methods.
Option names
The name of the options in this page use the "dot notation". But option names may differ depending on the chosen method to set them. Here you have a brief example of how the same option (mock.routes.delay
) must be defined when using different methods:
- Programmatic
- JS Config file
- YAML Config file
- Environment
- Command line argument
// Set mock.routes.delay option
const server = new Core({
mock: {
routes: {
delay: 3000,
},
},
});
Convert the "dot notation" into an object when setting programmatic configuration.
// Set mock.routes.delay option
module.exports = {
mock: {
routes: {
delay: 3000,
},
},
};
Convert the "dot notation" into an object when setting configuration using the config file.
mock:
routes:
delay: 3000
Convert the "dot notation" into an object when setting configuration using the config file.
MOCKS_MOCK_ROUTES_DELAY=3000 npm run mocks
Convert the "dot notation" into "screaming snake case", adding the MOCKS
prefix.
npm run mocks -- --mock.routes.delay=3000
Use the same "dot notation".
Core options
These options are provided by the core of Mocks Server, so they can be used in any Mocks Server distribution.
config.allowUnknownArguments
(Boolean): When set to true
, it allows to define unknown command line arguments. Default is false
. It can be defined in any source.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
config:
allowUnknownArguments: true
npm run mocks -- --config.allowUnknownArguments
MOCKS_CONFIG_ALLOW_UNKNOWN_ARGUMENTS=true npm run mocks
const server = new Core({
config: {
allowUnknownArguments: true,
},
});
config.fileSearchFrom
(String): Start searching for the configuration file from this folder, and keep searching up in the parent directories until arriving at the config.fileSearchStop
folder. Default is process.cwd
.
Examples
- Arguments
- Environment
- Programmatic
npm run mocks -- --config.fileSearchFrom configs/mocks-server
MOCKS_CONFIG_FILE_SEARCH_FROM='configs/mocks-server' npm run mocks
const server = new Core({
config: {
fileSearchFrom: "configs/mocks-server"
},
});
Note that it will search in all parent folders recursively until finding a file or arriving at the config.fileSearchStop
folder, which by default is also process.cwd
. So, if you define a config.fileSearchFrom
folder that is not under the process.cwd
path, you should also provide the config.fileSearchStop
folder. Otherwise, it would search recursively until the root path if no config file is found.
mocks-server --config.fileSearchFrom=../configs --config.fileSearchStop=../configs
config.fileSearchPlaces
(Array of Strings): Paths to search for the configuration file. Default is described in the configuration methods chapter. It can be defined in any source, except configuration files.
Examples
- Arguments
- Environment
- Programmatic
npm run mocks -- --config.fileSearchPlaces path/to/my-config.js path/to/my-config.yml
MOCKS_CONFIG_FILE_SEARCH_PLACES='["path/to/my-config.js","path/to/my-config.yml"]' npm run mocks
const server = new Core({
config: {
fileSearchPlaces: [
"path/to/my-config.js",
"path/to/my-config.yml"
],
},
});
config.fileSearchStop
(String): Directory where the search for the configuration file will stop. Default is process.cwd
.
Examples
- Arguments
- Environment
- Programmatic
npm run mocks -- --config.fileSearchStop /path/to/stop-folder
MOCKS_CONFIG_FILE_SEARCH_STOP='/path/to/stop-folder' npm run mocks
const server = new Core({
config: {
fileSearchStop: "/path/to/stop-folder",
},
});
config.readArguments
(Boolean): If false
, it disables the ability of defining options using command line arguments. Default is true
. It can be defined only using programmatic configuration.
Examples
- Programmatic
const server = new Core({
config: {
readArguments: false,
},
});
config.readEnvironment
(Boolean): If false
, it disables the ability of defining options using environment variables. Default is true
. It can be defined using programmatic configuration or command line arguments.
Examples
- Argument
- Programmatic
npm run mocks -- --no-config.readEnvironment
const server = new Core({
config: {
readEnvironment: false,
},
});
config.readFile
(Boolean): If false
, it disables the ability of reading configuration file. Default is true
. Obviously, it would be ignored if it is defined in the configuration file.
Examples
- Argument
- Environment
- Programmatic
npm run mocks -- --no-config.readFile
MOCKS_CONFIG_READ_FILE=false npm run mocks
const server = new Core({
config: {
readFile: false,
},
});
files.enabled
(String): Allows to disable loading routes and collections from files, which may be useful when used programmatically. Default is true
.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
files:
enabled: false
npm run mocks -- --no-files.enabled
MOCKS_FILES_ENABLED=false npm run mocks
const server = new Core({
files: {
enabled: false,
},
});
files.path
(String): Path to the folder containing collections and routes to be loaded by the server. Default is mocks
. When relative, it is resolved from the current process.cwd()
.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
files:
path: custom-folder
npm run mocks -- --files.path=custom-folder
MOCKS_FILES_PATH=custom-folder npm run mocks
const server = new Core({
files: {
path: path.resolve(__dirname, "custom-folder"),
},
});
files.watch
(Boolean): Watch the /mocks
folder and restart server on changes. Default is true
.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
files:
watch: false
npm run mocks -- --no-files.watch
MOCKS_FILES_WATCH=false npm run mocks
const server = new Core({
files: {
watch: false,
},
});
files.babelRegister.enabled
(Boolean): Enables Babel compilation for files inside the /mocks
folder.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
files:
babelRegister:
enabled: true
npm run mocks -- --files.babelRegister.enabled
MOCKS_FILES_BABEL_REGISTER_ENABLED=true npm run mocks
const server = new Core({
files: {
babelRegister: {
enabled: true,
},
},
});
files.babelRegister.options
(Object): Options for @babel/register
when babelRegister
is enabled. Properties in this object are passed directly to @babel/register
as options, so refer to its documentation for further info. You can also see some usage examples in the "using Babel" chapter of this docs.
Examples
- JS config file
- Programmatic
- Argument
- Environment
module.exports = {
files: {
babelRegister: {
enabled: true,
options: {
only: (filePath) => {
return filePath.includes("/mocks/") || filePath.includes("/my-folder-to-include/");
},
},
},
},
};
const server = new Core({
files: {
babelRegister: {
enabled: true,
options: {
only: (filePath) => {
return filePath.includes("/mocks/") || filePath.includes("/my-folder-to-include/");
},
},
},
},
});
npm run mocks -- --files.babelRegister.options="{\"extensions\":[\".ts\"]}"
MOCKS_FILES_BABEL_REGISTER_OPTIONS='{"extensions":[".ts"]}' npm run mocks
log
(String): Logs level. Can be one of silly
, debug
, verbose
, info
, warn
, error
or silent
.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
log: "silly"
npm run mocks -- --log=silent
MOCKS_LOG=debug npm run mocks
const server = new Core({
log: "verbose"
});
mock.collections.selected
(String): Collection to use when the server is started.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
mock:
collections:
selected: "my-collection"
npm run mocks -- --mock.collections.selected=my-collection
MOCKS_MOCK_COLLECTIONS_SELECTED=my-collection npm run mocks
const server = new Core({
mock: {
collections: {
selected: "my-collection"
}
}
});
mock.routes.delay
(Number): Responses delay time in milliseconds. This is a global setting that can be overridden in specific routes or route variants using their options.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
mock:
routes:
delay: 1000
npm run mocks -- --mock.routes.delay=1000
MOCKS_MOCK_ROUTES_DELAY=1000 npm run mocks
const server = new Core({
mock: {
routes: {
delay: 1000
}
}
});
plugins.register
(Array of Plugin
): Array of Plugins, defined as described in the plugins chapter.
Example
- Programmatic
import FooPlugin from "./FooPlugin";
const server = new Core({
plugins: {
register: [
FooPlugin,
]
}
});
server.cors.enabled
(Boolean): Built-in CORS middleware. Default is true
. Use false
to disable it.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
server:
cors:
enabled: false
npm run mocks -- --no-server.cors.enabled
MOCKS_SERVER_CORS_ENABLED=false npm run mocks
const server = new Core({
server: {
cors: {
enabled: false
}
}
});
server.cors.options
(Object): Options for the built-in CORS middleware. By default, it sets the preflightContinue
property as false
, which means that Mocks Server will respond to all OPTIONS
requests with a 204 status and correspondent CORS headers. If you want to handle OPTIONS requests by yourself, you should set that property to true
.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
server:
cors:
options:
preflightContinue: true
npm run mocks -- --server.cors.options="{\"preflightContinue\":true}"
MOCKS_SERVER_CORS_OPTIONS='{"preflightContinue":true}' npm run mocks
const server = new Core({
server: {
cors: {
options: {
preflightContinue: true
}
}
}
});
server.host
(String): Host for the server. Default is 0.0.0.0
(Reachable to all IPv4 addresses on the local machine).
Examples
- YAML config file
- Argument
- Environment
- Programmatic
server:
host: "192.168.1.100"
npm run mocks -- --server.host=192.168.1.100
MOCKS_SERVER_HOST=192.168.1.100 npm run mocks
const server = new Core({
server: {
host: "192.168.1.100"
}
});
server.https.enabled
(Boolean): Enables HTTPS protocol in the mock server. Default is false
Examples
- YAML config file
- Argument
- Environment
- Programmatic
server:
https:
enabled: true
npm run mocks -- --server.https.enabled
MOCKS_SERVER_HTTPS_ENABLED=true npm run mocks
const server = new Core({
server: {
https: {
enabled: true
}
}
});
When enabling the server.https.enabled
option, it is also needed to provide HTTPS certificate and key using the server.https.cert
and server.https.key
options. For further info read the "Enabling HTTPS" guide.
server.https.cert
(String): Path to a valid SSL/TLS certificate to be used when HTTPS is enabled. It must be relative to the current process.cwd()
or absolute. This option has no effect when server.https.enabled
is false
.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
server:
https:
cert: "certs/cert.pem"
npm run mocks -- --server.https.cert=certs/cert.pem
MOCKS_SERVER_HTTPS_CERT=certs/cert.pem npm run mocks
const server = new Core({
server: {
https: {
cert: "certs/cert.pem"
}
}
});
server.https.key
(String): Path to a valid SSL/TLS certificate key to be used when HTTPS is enabled. It must be relative to the current process.cwd()
or absolute. This option has no effect when server.https.enabled
is false
.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
server:
https:
key: "certs/key.pem"
npm run mocks -- --server.https.key=certs/key.pem
MOCKS_SERVER_HTTPS_KEY=certs/key.pem npm run mocks
const server = new Core({
server: {
https: {
key: "certs/key.pem"
}
}
});
server.jsonBodyParser.enabled
(Boolean): If false
, it disables the json
body-parser
built-in Express middleware. Default is true
.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
server:
jsonBodyParser:
enabled: false
npm run mocks -- --no-server.jsonBodyParser.enabled
MOCKS_SERVER_JSON_BODY_PARSER_ENABLED=false npm run mocks
const server = new Core({
server: {
jsonBodyParser: {
enabled: false,
}
}
});
server.jsonBodyParser.options
(Object): Options for the json
body-parser
built-in Express middleware.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
server:
jsonBodyParser:
options:
limit: "200kb"
npm run mocks -- --server.jsonBodyParser.options="{\"limit\":\"200kb\"}"
MOCKS_SERVER_JSON_BODY_PARSER_OPTIONS='{"limit":"200kb"}' npm run mocks
const server = new Core({
server: {
jsonBodyParser: {
options: {
limit: "200kb"
}
}
}
});
server.port
(Number): Port number for Mocks Server to be listening at. Default is 3100
.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
server:
port: 3500
npm run mocks -- --server.port=3500
MOCKS_SERVER_PORT=3500 npm run mocks
const server = new Core({
server: {
port: 3500
}
});
server.urlEncodedBodyParser.enabled
(Boolean): If false
, it disables the urlencoded
body-parser
built-in Express middleware. Default is true
.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
server:
urlEncodedBodyParser:
enabled: false
npm run mocks -- --no-server.urlEncodedBodyParser.enabled
MOCKS_SERVER_URL_ENCODED_BODY_PARSER_ENABLED=false npm run mocks
const server = new Core({
server: {
urlEncodedBodyParser: {
enabled: false,
}
}
});
server.urlEncodedBodyParser.options
(Object): Options for the urlencoded
body-parser
built-in Express middleware.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
server:
urlEncodedBodyParser:
options:
limit: "200kb"
npm run mocks -- --server.urlEncodedBodyParser.options="{\"limit\":\"200kb\"}"
MOCKS_SERVER_URL_ENCODED_BODY_PARSER_OPTIONS='{"limit":"200kb"}' npm run mocks
const server = new Core({
server: {
urlEncodedBodyParser: {
options: {
limit: "200kb"
}
}
}
});
variantHandlers.register
(Array of Variant Handlers
): Array of Variant Handlers
to be added. Other variant handlers are not removed.
Example
- Programmatic
import FooVariantHandler from "./FooVariantHandler";
const server = new Core({
variantHandlers: {
register: [
FooVariantHandler,
]
}
});
Plugins options
Each plugin can add its own options when it is installed. These options can also be defined and changed using the same methods as the core options. Note that all plugins options must be defined under the plugins
namespace, and all options of a plugin must be defined under its own plugin id namespace (plugins.[plugin-id].[option]
)
These extra options are added by the plugins included in the @mocks-server/main
distribution.
For another plugins options, please refer to their own documentation.
plugins.inquirerCli.enabled
(Boolean): Start interactive CLI plugin or not. Default is true
.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
plugins:
inquirerCli:
enabled: false
npm run mocks -- --no-plugins.inquirerCli.enabled
MOCKS_SERVER_PLUGINS_INQUIRER_CLI_ENABLED=false npm run mocks
const server = new Core({
plugins: {
inquirerCli: {
enabled: false,
}
}
});
plugins.inquirerCli.emojis
(Boolean): Defines whether the inquirer CLI uses emojis or not. Default is true
.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
plugins:
inquirerCli:
emojis: false
npm run mocks -- --no-plugins.inquirerCli.emojis
MOCKS_SERVER_PLUGINS_INQUIRER_CLI_EMOJIS=false npm run mocks
const server = new Core({
plugins: {
inquirerCli: {
emojis: false,
}
}
});
plugins.adminApi.host
(String): Host for the administration REST API. Default is 0.0.0.0
(Reachable to all IPv4 addresses on the local machine).
Examples
- YAML config file
- Argument
- Environment
- Programmatic
plugins:
adminApi:
host: "192.168.1.100"
npm run mocks -- --plugins.adminApi.host=192.168.1.100
MOCKS_SERVER_PLUGINS_ADMIN_API_HOST_=192.168.1.100 npm run mocks
const server = new Core({
plugins: {
adminApi: {
host: "192.168.1.100",
}
}
});
plugins.adminApi.https.enabled
(Boolean): Enables HTTPS protocol in the admin API server. Default is false
Examples
- YAML config file
- Argument
- Environment
- Programmatic
plugins:
adminApi:
https:
enabled: true
npm run mocks -- --plugins.adminApi.https.enabled
MOCKS_PLUGINS_ADMIN_API_HTTPS_ENABLED=true npm run mocks
const server = new Core({
plugins: {
adminApi: {
https: {
enabled: true
}
}
}
});
When enabling the plugin.adminApi.https.enabled
option, it is also needed to provide HTTPS certificate and key using the plugin.adminApi.https.cert
and plugin.adminApi.https.key
options. For further info read the "Enabling HTTPS" guide.
plugins.adminApi.https.cert
(String): Path to a valid SSL/TLS certificate to be used when HTTPS is enabled in the adminApi
plugin. It must be relative to the current process.cwd()
or absolute. This option has no effect when server.https.enabled
is false
.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
plugins:
adminApi:
https:
cert: "certs/cert.pem"
npm run mocks -- --plugins.adminApi.https.cert=certs/cert.pem
MOCKS_PLUGINS_ADMIN_API_HTTPS_CERT=certs/cert.pem npm run mocks
const server = new Core({
plugins: {
adminApi: {
https: {
cert: "certs/cert.pem"
}
}
}
});
plugins.adminApi.https.key
(String): Path to a valid SSL/TLS certificate key to be used when HTTPS is enabled. It must be relative to the current process.cwd()
or absolute. This option has no effect when plugins.adminApi.https.enabled
is false
.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
plugins:
adminApi:
https:
key: "certs/key.pem"
npm run mocks -- --plugins.adminApi.https.key=certs/key.pem
MOCKS_PLUGINS_ADMIN_API_HTTPS_KEY=certs/key.pem npm run mocks
const server = new Core({
plugins: {
adminApi: {
https: {
key: "certs/key.pem"
}
}
}
});
plugins.adminApi.port
(Number): Port for the administration REST API. Default is 3110
.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
plugins:
adminApi:
port: 3510
npm run mocks -- --plugins.adminApi.port=3510
MOCKS_SERVER_PLUGINS_ADMIN_API_PORT=3510 npm run mocks
const server = new Core({
plugins: {
adminApi: {
port: 3510,
}
}
});
plugins.openapi.collection.id
(String | Null): Id for the collection to be created with all routes from all OpenAPI documents. Default is "openapi". When it is set to null
, no collection will be created.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
plugins:
openapi:
collection:
id: "all-openapi-routes"
npm run mocks -- --plugins.openapi.collection.id=all-openapi-routes
MOCKS_SERVER_PLUGINS_OPENAPI_COLLECTION_ID=all-openapi-routes npm run mocks
const server = new Core({
plugins: {
openapi: {
collection: {
id: "all-openapi-routes"
},
}
}
});
plugins.openapi.collection.from
(String): Id of the collection to extend from when creating the collection with all routes from all OpenAPI documents.
Examples
- YAML config file
- Argument
- Environment
- Programmatic
plugins:
openapi:
collection:
from: "base"
npm run mocks -- --plugins.openapi.collection.from="base"
MOCKS_SERVER_PLUGINS_OPENAPI_COLLECTION_FROM=base npm run mocks
const server = new Core({
plugins: {
openapi: {
collection: {
from: "base"
},
}
}
});