Skip to main content
Version: 4.0.0



Packages versioning

This project adheres to Semantic Versioning 2.0 rules.

The project mainly consists on NPM packages published to the NPM registry, and each one its versioned independently following the Semver rules.

In the Github repository, which is a monorepo, the releases are usually tagged following the versions of @mocks-server/main package. Releases in other packages that don't affect to the @mocks-server/main version are tagged as fixes of the latest version.

Docker images versioning

Docker images does not follow strictly the Semver rules. They are versioned based on the version of the Mocks Server package they execute. Here you have a table with the correspondences between Mocks Server NPM packages and the Docker images. In case a modification has to be made in a Docker image without implying a new package version, it will be released as a bug fix, so, only the patch version would be upgraded.

Docker imageNPM package

The Node.js version used on each new release of a Docker image will be the active one on that date.

Website versioning

This documentation website does not follow the Semver rules, but it is versioned following the versions of @mocks-server/main package. Each minor or major release of that package produces this documentation to be versioned as well. Fixes in that package or releases in other packages that don't affect to the @mocks-server/main version, but should be documented, are updated in the current version of this docs.

Usually, we only keep published the first major version and the latest minor version of each major release. Other minor releases docs are removed, except the previous minor release of the current version.

Major releases

Introducing great breaking changes is something that we always try to avoid on each new major version in order to make as much easy as possible the migration to the users. Usually, when something is going to be deprecated, a backward compatibility mechanism is provided in minor versions, so, users can start using the new features while still use some other legacy ones, and progressively migrate and stop using them in favor of the new features. Then, the migration to the next major version can be made with lower effort and progressively.


When backward compatibility mechanisms are provided and something is going to be deprecated, you would usually receive alerts in the logs or in the interactive CLI. So, you can know which things should be changed before upgrading to the next major version.


Here you have a brief summary of the main changes of each release. For a full detailed history of the correspondent versions of each package, please check out the Github repository release notes

NOTE: Release notes prior to the monorepo migration

All packages were migrated to a monorepo from release v2.6.3. Release notes of previous releases in the mocks-server/main repository don't include details about changes in other packages. So, for details about previous releases of other packages, please refer to each package's file or to old repositories release notes. Old repositories are maintained as publicly archived repositories in the mocks-server Github project.



Read the how to migrate from v3 to v4 guide for further info about next BREAKING CHANGES:

  • Removed legacy properties in collections and variants.
  • Removed legacy options
  • Removed legacy methods in the JavaScript API
  • Removed legacy Administration REST API path
  • Removed legacy formats for defining plugins, and removed legacy plugin parameters.
  • Removed legacy format for defining variant handlers.
  • Removed legacy proxy handler. proxy-v4 handler renamed into proxy.
  • Added support for .cjs files out of the box



  • Add config.fileSearchFrom and config.fileSearchStop options



  • OpenAPI integration. Add plugin-openapi to the main distribution
  • Support asynchronies in files. Files in the "/mocks" folder can export an async function
  • Support nullable options in configuration



  • HTTPS support. Add related options to core and plugin-admin-api



  • YAML support in routes and collections files
  • Files JavaScript API



  • Files and Status variant handlers
  • Cypress commands supporting multiple Mocks Servers
  • Cypress commands logs



  • Static and Text variant handlers
  • Add disabled property to variants
  • Support method * in routes
  • Support property router in Variant Handlers
  • Add default content-type header to json Variant Handler



  • Rename concepts into collections, routes and variants. Adapt website and APIs to the new concepts.
  • Publish new core.mock API. Deprecate core.onChangeMocks, core.loadMocks, core.loadRoutes and all core.mocks methods.
  • Add new options files.enabled, mock.routes.delay and mock.collections.selected * Add option. Deprecate mocks.delay and mocks.selected
  • Support type and options properties in variants
  • Support routes and routeVariants properties in collections. Deprecate routesVariants
  • Add core.version getter
  • Deprecate core.alerts when used out of plugins
  • Export createServer function returning a core instance with preinstalled plugins



  • Add Json and Middleware variant handlers.
  • Support deprecated property in route handlers. Add an alert whenever any route variant uses a deprecated handler
  • Pass only response property from variants to route variant handlers having the version property defined as "4". If it has another value, pass the whole variant object (for backward compatibility)



  • Add an alert when plugins are not defined as Classes. Other formats will not be supported in next major version



  • Add update notifier. Display an alert in case package is out of date
  • Add advancedOptions parameter to Core constructor. Add pkg option allowing to determine name and version for update notifier.



  • Add onChangeLogs method, allowing to execute a callback whenever logs changes.
  • Use new logger. Deprecate tracer in core API. Provide namespaced loggers to plugins.
  • Pass custom core to route variant middlewares and route handlers. The alerts and logger properties are namespaced for each different route variant
  • Pass new custom core API to plugins. All core methods are available in the first parameter. The core property is still available for backward compatibility, but using it produces an alert



  • Pass new alerts API to plugins. Add an alert if old addAlert or removeAlerts methods are used.



  • BREAKING CHANGE. Configuration format changed. All options have been renamed or moved into namespaces. Please check the docs in the website for further info
  • BREAKING CHANGE. Change arguments passed to the plugins. Now there is only one argument with an object containing everything.
  • BREAKING CHANGE. ajv-errors is not used any more. Now, better-ajv-errors is used to provide better feedback about validations. So ajv-errors properties for json schemas are not supported any more.
  • BREAKING CHANGE. Remove support for legacy "behaviors"
  • A namespaced configuration object is passed to plugins if they have an id property.
  • Configuration can be defined also in environment variables
  • Configuration can be defined in different file formats, using cosmiconf
  • Add config getter to core



  • Add Proxy route variant



  • Support Node.js 17.x



  • Support application/x-www-form-urlencoded



  • Validate routes and collections



  • Babel support



  • Support multiple methods in routes
  • Add cors option



  • Rename concepts to routes and mocks. Support using legacy behaviors in a different folder at the same time, in order to allow a progressive migration.
  • Add new Mocks and Routes handler, and related getters to core
  • Add new plugin for loading files with routes and mocks in v2 format



  • Add alerts and display them in the interactive CLI



  • Configuration file
  • Node.js v15.x support



  • Support defining behaviors and mocks in JSON



  • Add administration REST API



  • Support custom variant handlers



  • Change "behaviors" option by "path", now it has "mocks" value by default.



  • Plugins approach refactor. First version of the @mocks-server/core package



  • Catch server.listen error and reject start method promise when occurs



  • Change "feature" concept by "behavior". Maintain old "feature" options and urls as aliases for maintaining compatibility.



  • Project migration. Forked from xbyorange/mocks-server. Fixed license. Read NOTICE file for further details