webpack-mock-server

Mocks api requests for webpack-dev-server with hot-replacement

Usage no npm install needed!

<script type="module">
  import webpackMockServer from 'https://cdn.skypack.dev/webpack-mock-server';
</script>

README

Webpack Mock Server

ExpressJs Middleware for webpack-dev-server with built-in hot-replacement (HMR) and typescript compiler. Uses for mocking api responses

npm version install size npm downloads License: MIT

Features

  • Typescript support (>=v2.7): supports .js, .ts, .json files
  • ES6 export/import support
  • Hot replacement support
  • Does not require proxy-path-pattern (because this is middleware that pipes routes to splitted server without proxy-path-pattern)
  • Can be used without webpack (because this is expressjs middleware)
  • Shows every configured response in user-friendly index.html (just click on mock-server-url in console after as mockServer is started)

Installing

Using npm (installing Typescript is required even if you don't use ts files):

npm install --save-dev webpack-mock-server typescript

Examples

Usage with defaults

// webpack.config.js
const webpackMockServer = require("webpack-mock-server");

module.exports = {
  devServer: {
    before: webpackMockServer.use
  }
}

// webpack.mock.ts - feel free to mock responses yourself
import webpackMockServer from "webpack-mock-server";
import nodePath from "path";

// app is expressjs application
export default webpackMockServer.add((app, helper) => {
  // you can find more about expressjs here: https://expressjs.com/
  app.get("/testGet", (_req, res) => {
    res.json("JS get-object can be here. Random int:" + helper.getRandomInt());
  });
  app.post("/testPost", (_req, res) => {
    res.json("JS post-object can be here");
  });

  // you can return any file easy. Example for json response from file:
   app.get("/testResponseFromJsonFile", (_req, res) => {
    res.sendFile(nodePath.join(__dirname, "./response.json"));
  });
})

// multiple exports are supported
export const result = webpackMockServer.add((app, helper) => {
  app.delete("/testDelete", (_req, res) => {
    res.json("JS delete-object can be here. Random int:" + helper.getRandomInt());
  });
  app.pust("/testPut", (_req, res) => {
    res.json("JS put-object can be here");
  });
})

Usage with multiple/custom entries (instead of default webpack.mock.ts)

// webpack.config.js
const webpackMockServer = require("webpack-mock-server");

module.exports = {
  devServer: {
    before: app =>
        webpackMockServer.use(app, { // MockServerOptions here
          entry: [ // exact fileNames are expected (no wildcard or folder - use custom tsConfig instead)
              "api/users.mock.ts",
              "api/goods.mock.js"
          ],
          before: (req, res, next) => { // you can use this for custom-logging instead of logResponses: true, logRequests: true
              console.log(`Got request: ${req.method} ${req.url}`);
              res.once("finish", () => {
                 console.log(`Sent response: ${req.method} ${req.url}`);
               })
              next();
          }
      })
  }
}

// api/users.mock.ts
... // take the example for ts-file above

// api/goods.mock.js
export default webpackMockServer.add((app, helper) => {
  app.get("/testGetGoods", (_req, res) => {
    res.json([{
        id: helper.getRandomInt(1, 999),
        name: "pen"
    }]);
  });
})

Usage with multiple entries by pattern (wildcard)

// webpack.config.js
const webpackMockServer = require("webpack-mock-server");

module.exports = {
  devServer: {
    before: app =>
      webpackMockServer.use(app, {
          /* set an empty-array or null to [entry], so entry will be defined
              from 'files' and 'includes' sections in [tsConfigFileName]
          */
          entry: [],
          tsConfigFileName: "mock/tsconfig.json" // use a different tsconfig-file that is contained entries
      })
  }
}

// ./mock/tsconfig.json
{
/*
    this is ordinary tsconfig file that overrides every option from [extends] - main tsconfig-file
*/
  "extends": "../tsconfig.json", // you can point the main tsconfig file or remove that property if it's not required
  "include": [  // wildcard-pattern is supported
      "../mock/*",
      "*.mock.ts"
  ],
  "files": [], // beside 'include' option you can point exact files here
  "exclude": ["*test.mock.ts"] // note: exclude option can override 'include' and 'files' options
}

Usage without webpack

As expressjs middleware: http://expressjs.com/en/guide/using-middleware.html

// webpack.config.js
const webpackMockServer = require("webpack-mock-server");

const express = require('express');
const app = express();

webpackMockServer.use(app, {/*mockServerOptions*/})
...
app.listen(1782);

// webpack.mock.ts - example you can find above
...

Usage with the whole default config

// webpack.config.js
...
const webpackMockServer = require("webpack-mock-server");

module.exports = {
  devServer: {
    before: app =>
      webpackMockServer.use(app, {
          port: 8079, // app searches for free port (starts searching from pointed)
          verbose: false, // send info via console.log
          logRequests: false,
          logResponses: false,
          before: undefined, //can be used for logging
          entry: ["webpack.mock.ts"],
          tsConfigFileName: "tsconfig.json",
          compilerOptions: { // typescript.CompilerOptions that override tsconfig.json:[compilerOptions]
              strictNullChecks: false,
              noImplicitAny: false,
              noUnusedLocals: false,
              noUnusedParameters: false,
              skipLibCheck: true,
              resolveJsonModule: true
          },
          strictCompilerOptions: { // these options impossible to override
              outDir: "" // used the following: {os.tmpdir()}/webpack-mock-server/{new Date().getTime()}
              rootDir: process.cwd(),
              noEmit: false,
              noEmitHelpers: false,
              esModuleInterop: true,
              module: ts.ModuleKind.CommonJS,
              declaration: false,
              moduelResolution: ModuleResolutionKind.NodeJs,
              target: defineTarget() // it defines target-ES based on NODE version
          }
      })
  }
}

// webpack.mock.ts - example you can find above
...

Options

Note: Every path-file-name in options has to be pointed relative to the currentWorkingDirectory (process.cwd() in NodeJs) or point an absolute path

Param Type Default Description
entry String, String[], null ["webpack.mock.ts"] Entry points for typescript-compiler (exact fileNames are expected). Set an empty array or null for using files, include and exlcude sections from tsConfigFileName. Otherwise these sections are ignored!
port Number 8079 App searches for free port (starts searching from pointed)
verbose Boolean false Show debug info in NodeJs via console.log
logResponses Boolean false Show responses-info in NodeJs via console.log
logRequests Boolean false Show request-info in NodeJs via console.log
before (req, res, next) => void undefined Execute custom middleware prior to all other middleware internally within the server Can be used for custom-logging. Example here
compilerOptions typescript.CompilerOptions ... See the latest example above
strictCompilerOptions typescript.CompilerOptions ... readOnly. See the latest example above. These options impossible to override
tsConfigFileName String "tsconfig.json" Pointer to typescript config file. Example here:

MockServerHelper. Methods

Troubleshooting

  • It's important to install Typescript even if use only JS-files (webpack-mock-server uses ts-compiler for gathering ts,js,json files)
  • Don't use NodeJs require operator as dynamic to relative path. Use __dirname in this case or absolute path (__dirname is changed during the compilation)
  • NodeJs caches every required module (file), so you maybe interested in clearing cache for require(.json)*. Use delete require.cache[require.resolve({yourPathName})] before you call require({yourPathName});
// Wrong
app.get("/testResponseFromJsonFile", (_req, res) => {
  res.sendFile(require.resolve("./response.json"));
});

app.get("/testResponseFromJsonFile2", (_req, res) => {
    res.json(require("./response.json"));
});
  
// Good
import nodePath from "path";

app.get("/testResponseFromJsonFile", (_req, res) => {
  res.sendFile(nodePath.join(__dirname, "./response.json"));
});

app.get("/testResponseFromJsonFile2", (_req, res) => {
  /* From NodeJs v8.9.0 you can use options: path
   * const resolvedPath = require.resolve("./response.json", { paths: [__dirname] });
   */
  const resolvedPath = require.resolve(nodePath.join(__dirname, "./response.json"));  
  // removing NodeJS cache for getting the latest file
  delete require.cache[resolvedPath];
  res.json(require(resolvedPath));
});