smoke
A file-based mock server that uses folder structures and file names to define API routes, with recording and templating capabilities.
What is smoke?
Smoke is a file-based mock server for Node.js that allows developers to simulate API responses by organizing JSON, HTML, or JavaScript files in a directory structure. It solves the problem of setting up complex mock servers by using a convention-over-configuration approach, where file names and folders directly map to API routes and HTTP methods.
Frontend and backend developers who need to mock APIs for testing, prototyping, or development without relying on a live backend. It's especially useful for teams practicing contract-first development or working in offline environments.
Developers choose Smoke for its zero-configuration setup, powerful recording features, and flexibility—it supports dynamic templating, JavaScript mocks, and middleware hooks while keeping the learning curve low due to its file-based nature.
Overview
:dash: Simple yet powerful file-based mock server with recording abilities
Use Cases
Best For
- Mocking REST APIs during frontend development before the backend is ready
- Recording API responses from a live server to create a reusable mock suite
- Testing different API scenarios (e.g., error responses, edge cases) using mock sets
- Prototyping API designs with dynamic responses based on request parameters
- Simulating slow or faulty API behavior with custom middleware hooks
- Creating offline development environments by mocking external dependencies
Not Ideal For
- Projects requiring real-time WebSocket or GraphQL mocking, as Smoke focuses on HTTP-based REST APIs via static files.
- Teams preferring GUI-based mock management tools, since Smoke relies entirely on CLI and file system operations.
- Environments with highly dynamic, stateful APIs that need in-memory data persistence across requests.
- Large-scale microservices with hundreds of endpoints, where file organization could become cumbersome and slow.
Pros & Cons
Pros
Simply drop files in a folder to define routes and responses, eliminating boilerplate code—just run 'smoke' and start mocking.
Proxy and record responses from a live server with --record, automatically generating mock files for offline use or rapid suite creation.
Use template syntax (e.g., {{query.name}}) in files to generate responses based on request data, making mocks more realistic and adaptable.
Write custom .js modules for complex logic and add Express-compatible middleware hooks, allowing advanced request/response manipulation.
Cons
The naming convention for methods, routes, and parameters (e.g., 'get_api#hello$who=john.json') is complex and error-prone, requiring URL encoding for special chars.
Heavy reliance on files can slow down large mock sets and makes it unsuitable for stateful APIs that require runtime data persistence.
Version 4 switched to ES modules by default, forcing users to rename .js files to .cjs or update syntax if migrating from older versions, as noted in the README.
Lacks a visual interface for creating or managing mocks, which may hinder adoption in teams accustomed to point-and-click tools.
Frequently Asked Questions
Related Projects
axiosPromise based HTTP client for the browser and node.js
superagentAjax for Node.js and browsers (JS HTTP client). Maintained for @forwardemail, @ladjs, @spamscanner, @breejs, @cabinjs, and @lassjs.
got🌐 Human-friendly and powerful HTTP request library for Node.js
node-fetchA light-weight module that brings the Fetch API to Node.js
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.