Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
apiMocker
✓ import apiMocker from 'mocker-api';
✗ const apiMocker = require('mocker-api');
Since v3, `mocker-api` primarily uses ESM imports. While `require` might work with transpilation, direct ESM import is recommended. CommonJS usage can lead to errors like 'default is not a function' in certain environments.
MockerAPIOptions
✓ import type { MockerAPIOptions } from 'mocker-api';
Imports for type definitions, such as the options object passed to the main `apiMocker` function, should use `import type` to ensure they are stripped at compile time.
MockDefinition
✓ // In mocker/index.ts:
interface User { id: number; name: string; }
const mocks: Record<string, User | User[]> = {
'GET /api/users': [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }],
'GET /api/user/:id': (req, res) => {
const id = parseInt(req.params.id, 10);
if (id === 1) return res.json({ id: 1, name: 'Alice' });
if (id === 2) return res.json({ id: 2, name: 'Bob' });
res.status(404).json({ message: 'User not found' });
},
};
export default mocks;
Mock definitions are typically objects or functions exported from user-defined files, which are then loaded by `mocker-api`. The library expects a specific structure for these definitions (e.g., path strings mapped to data or handler functions).
This quickstart sets up a basic Express server and integrates `mocker-api` as middleware. It demonstrates defining mock API routes in a separate file (e.g., `mocker/index.ts`), handling both static JSON responses and dynamic request/response logic, and includes an example of proxying unmocked requests to a real API like JSONPlaceholder or GitHub for a seamless development experience.
import express from 'express';
import path from 'path';
import apiMocker from 'mocker-api';
interface User { id: number; name: string; email: string; }
// --- Create 'mocker/index.ts' file in your project root or source directory ---
// const mocks = {
// 'GET /api/users': [
// { id: 1, name: 'Alice', email: 'alice@example.com' },
// { id: 2, name: 'Bob', email: 'bob@example.com' },
// ],
// 'POST /api/users': (req, res) => {
// const newUser: User = { id: Date.now(), ...req.body };
// console.log('New user created:', newUser);
// res.status(201).json(newUser);
// },
// 'GET /api/user/:id': (req, res) => {
// const userId = parseInt(req.params.id, 10);
// const users: User[] = [
// { id: 1, name: 'Alice', email: 'alice@example.com' },
// { id: 2, name: 'Bob', email: 'bob@example.com' },
// ];
// const user = users.find(u => u.id === userId);
// if (user) {
// res.json(user);
// } else {
// res.status(404).json({ message: `User with ID ${userId} not found` });
// }
// },
// 'GET /api/posts': [
// { id: 101, title: 'First Post' },
// { id: 102, title: 'Second Post' },
// ],
// // Example of proxying specific requests: anything starting with /github/
// 'GET /github/*': 'https://api.github.com/',
// };
// export default mocks;
// -----------------------------------------------------------------------------
const app = express();
const port = process.env.PORT ?? 8080; // Use process.env.PORT or default to 8080
// Enable JSON body parsing for POST/PUT requests (essential for 'POST /api/users' mock)
app.use(express.json());
// Resolve the path to your mock definition file.
// Ensure 'mocker/index.js' or 'mocker/index.ts' exists and exports the mock definitions.
const mockDirectory = path.resolve(__dirname, 'mocker/index.js'); // Adjust for your build output
apiMocker(app, mockDirectory, {
// Optional: Enable proxying for unmocked routes. Requests matching '/api/(.*)'
// that are not explicitly mocked will be forwarded to JSONPlaceholder.
proxy: {
'/api/(.*)': 'https://jsonplaceholder.typicode.com/',
},
// Set changeHost to true when proxying to external hosts like GitHub API to avoid CORS issues.
changeHost: true,
// Optional: Simulate network delay for all mock responses in milliseconds.
delay: 500,
});
app.listen(port, () => {
console.log(`Mock API Server is running at http://localhost:${port}`);
console.log('Try visiting:');
console.log(`- http://localhost:${port}/api/users (mocked data from 'mocker/index.ts')`);
console.log(`- http://localhost:${port}/api/user/1 (mocked data from 'mocker/index.ts')`);
console.log(`- http://localhost:${port}/api/todos/1 (proxied to JSONPlaceholder)`);
console.log(`- http://localhost:${port}/github/users/jaywcjlove (proxied to GitHub API)`);
});
Errors
Common errors & fixes
TypeError: (0 , _mockerApi.default) is not a function
This error typically occurs when attempting to import an ESM module using a CommonJS `require()` syntax, or when a bundler incorrectly transpiles ESM to CJS, expecting a `.default` property on the imported module.
fixEnsure you are using ESM `import apiMocker from 'mocker-api';` syntax. If using CommonJS, check your `tsconfig.json` (for TypeScript) or Babel configuration to ensure correct module resolution and transpilation for ESM packages. For Node.js, ensure your environment supports ESM or use a tool like `ts-node` with appropriate settings.
Error: Cannot find module 'express'
The `express` package is a common dependency for `mocker-api` usage, especially when integrating it into an Express.js application, but it might be a peer dependency or simply an assumed external dependency, not automatically installed by `mocker-api` itself.
fixInstall `express` as a dependency in your project: `npm install express` or `yarn add express`.
Error: Mock file path '/path/to/nonexistent/mocker/index.js' is invalid or mock data is not an an object or function.
The `apiMocker` function expects a valid path to a JavaScript/TypeScript file that exports an object or a function containing your mock definitions, or it expects a direct mock object. This error indicates the file was not found, or its export was not in the expected format.
fixVerify that the path provided to `apiMocker` (e.g., `path.resolve(__dirname, 'mocker/index.js')`) correctly points to an existing file, and that the file exports either an object of mock definitions or a function that returns such an object. Ensure the file is accessible and free of syntax errors.
Error: EADDRINUSE: address already in use :::8080
This error occurs when the port specified for the Express server (e.g., 8080) is already being used by another application or process on your system.
fixChange the `port` variable in your `app.listen()` call to an available port (e.g., 3000, 8000, 9000). You can also use tools like `lsof -i :8080` (macOS/Linux) or `netstat -ano | findstr :8080` (Windows) to identify and terminate the process using the port, if appropriate.
Audit
Dependencies
expressoptionalCommonly used as middleware for Express.js applications to serve mock APIs.
webpack-dev-serveroptionalOften integrated into webpack configurations to provide API mocking during development.