Bring the best of OSS JavaScript development to your projects with npm Orgs - private packages & team management tools.Learn more »


2.2.4 • Public • Published


NPM Version Build Status codecov License

A static server, with easy extendability to become mock server, via flexible configuring of response from file, inline data, function and more.


  • both CLI and API
  • multiple instances with different working directories
  • url to file path mapping
  • simple configuring for any http status code
  • full ability to manipulate request and response
  • support https



npm i -g flex-mock-server


  • fms
  • flex-mock-server


  • -d, --debug: Verbose information for debugging.
  • -p, --port [port]: Server port, default is 3000.
  • -c, --cwd [dir]: Current working directory, default to process.cwd(); mock folder and map file path are based on this.
  • -f, --folder [dir]: Mock files residing directory.
  • -m, --map [fileName]: Custom response map file path; see example below.
  • -i, --index [fileName]: Default html page file name for existing bare folder.
  • -h, --history [fileName]: Whether to support html5 history api, alike "historyApiFallback" of webpackDevServer. if string, it is a path relative to cwd, to which the requested file resorts when directory non-exists; if true, then the resorting file path is set to index.
  • -C, --cors: Allow cors
  • -k, --cors-cookie: Allow cors credential. When set, cors is implied to be true.
  • -o, --auto-preflight: Handle "OPTIONS" method automatically, bypassing checking map configs. default is true.
  • -r, --root [dir]: Virtual root directory where this app is mounted in the domain, alike webpack "publicPath", which will be removed when match file.
  • -H, --https: Whether to apply https.
  • -h, --help: Output usage information.



npm i -D flex-mock-server


import Server from 'flex-mock-server';
// const Server = require('flex-mock-server').default;
const params = {};
const server = new Server(params);
server.onError((error) => console.error(error));

Multiple instances could be created with different cwd.


  • debug {bool}
  • port {Number}
  • cwd {string}
  • folder {string}
  • map {string|Object}
  • index {string}
  • history {string}
  • cors {bool}
  • corsCookie {bool}
  • autoPreflight {bool}
  • root {string}

Refer to cli options.

standard code-handler

Utility function for before and data handlers to response with default status code behavior.


import { StandardCodeHander } from 'flex-mock-server';
// const StandardCodeHander = require('flex-mock-server').StandardCodeHander;
module.exports = {
  'dir/file.html': function customHandler(req, res, passedThroughData, logger){
    return StandardCodeHander(req, res, 302, {location: ''}, logger);

map file


  pattern: response


A string to construct RexExp for url testing and replacing with file path.


  • The url being matched against is whatever left after removing domain and root directory (if supplied). e.g. /dir1/dir2/abc.ext in
  • Backslash should be escaped if you hope it take effects in constructed RegExp: file\\.html


Allowed types are:

  • {Number}: Treated as http code, being handled automatically; returns intermediately.

  • {Array}: An array, http code along with corresponding data: [301, '']

  • {object}: a json of complex type, fields are:

    • before {function(req, res, logger)}: Execute before processing, to modify request or whatever.

    • after {function(req, res, responseData, logger)}: Called after response data is got and before sent.
      if binary data, fs.ReadStream is passed instead of file content.

    • data {*}: (match for any type of METHOD)

      • non-function Inline respone data for any method; This data is sent instead of from file.
      • function(req, res, passedThroughData, logger) Custom handler. returns
        1. the response data;
        2. a promise that resolves the response data (polyfill was already applied).

      don't call respone.end()/write() yourself.

    • path {string | function}: file path.

      • {string} - mapped file path string, internally it is called with String.replace(), so special replacement patterns are supported, such as $&, $', $1.
      • {function(req, res, logger)} - custom replacer.
    • passThrough {bool}: whether to check left items for more matches and pass this data on. default is false.

    • get/post/... {*}: method respective version of 'data'. }

  • {string}: shorthand for string version of path: {path:''}

  • {function}: shorthand for function version of data: { data: func }

This map is walked through twice. The first time matched "before" handlers are executed. The second time to retrieve response data. However if the first time encounters a standard code handler, e.g. type of config is Number/Array, traversing stops, returns immediately.


Passed in parameter logger in custom handlers is used to output information for debugging when debug flag is turned on. Three methods are supplied.

  • error(...args): red color
  • info(...args): blue color
  • log(...args): white color


  • babel-polyfill v6.26.0 is applied, New es6/7 features could be used in this map file.
  • A sample map file exists with path of lib/, contents are:


const url = require('url');

module.exports = {
  // standard code
  '/code/401/file\\.htm': 401,
  // standard code with arguments
  '/code/301/.*': [301, { url: '' }],
  // custom data for any methods.
  '/data/null': { data: null },
  '/data/empty-string\\.htm': { data: '' },
  '/data/string': { data: 'hello world' },
  '/data/number': { data: 1 },
  '/data/json': { data: { customData: '123' } },
  // custom handler returning plain data.
  '/data/func/plain': {
    data(req, res, logger) {
      const parsedUrl = url.parse(req.url, true);
      const params = parsedUrl.query;
      if ( == 1) { // eslint-disable-line eqeqeq
        return { success: false };
      return { success: true };
  // custom handler returning plain promise.
  '/data/func/promise': function handle(req, res, logger) {
    return new Promise((resolve, reject) => {
      resolve({ data: 'abc' });
  // shorthand for { data: func }
  '/func/file\\.htm': function handle(req, res, logger) {
    return { success: true };
  // explicit method handler prioritized over 'data'.
  '/post/file\\.htm': {
    post: { customData: '456' },

  // pre-processing handler to redirect to another path defined before.
  '/before/.*': {
    before(req, res, logger) {
      req.url = '/data/json';

  // don't pass through to 'compound/.*' by default.
  '/compound/no-through': {
    data(req, res, data, logger) {
      return { value: 0, success: false };
  // pass through to next two items by setting 'passThrough' to true.
  '/compound/through/file\\.htm': {
    data(req, res, data, logger) {
      return { value: 1 };
    passThrough: true,
  '/compound/through/.*': {
    data(req, res, data, logger) {
      return data;
    passThrough: true,
  // "after" handler to modify response data
  '/compound/.*': {
    after(req, res, data, logger) {
      if (typeof data === 'string') { // read from file
        data = JSON.parse(data);
      data.success = true;
      return data;

  // direct file path mapping
  '/path/article/(\\d+)/comment/(\\d+)': {
    path: 'article_$2_comment_$1.json',
  // custom file path mapping
  '/path/custom/article/(\\d+)/comment/(\\d+)': {
    path(req, res, logger) {
      return req.url.replace(
        new RegExp('path/custom/article/(\\d+)/comment/(\\d+)'),
  // shorthand for { path }
  '/path/short/article/(\\d+)/comment/(\\d+)': 'article_$2_comment_$1.json',




npm i flex-mock-server

Downloadsweekly downloads









last publish


  • avatar
Report a vulnerability