json-server

library0.1.3jsnpmunverified

json-server is a lightweight Node.js tool for rapidly creating a full fake REST API from a JSON or JSON5 file, requiring virtually no coding. It is currently in active development with a `v1.0.0-beta.x` series (current: `v1.0.0-beta.15`), and new beta versions are released frequently, sometimes multiple times a week, as features are added and fixes applied. The last stable release is `v0.17.4`. Its primary differentiation lies in its simplicity and speed, making it an ideal choice for frontend development prototyping, mobile app mocking, and quick testing environments where a real backend is not yet available or too complex to set up. It automatically handles typical REST operations (GET, POST, PUT, PATCH, DELETE) and supports advanced features like filtering, sorting, pagination, and relationships based on the structure of the provided data file.

web-framework http-networking testing data

npm install json-server

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JSON-SERVER

json-server

web-frameworkjavascriptv0.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

jsonServer

✓ import jsonServer from 'json-server';

✗ import { jsonServer } from 'json-server';

This is the default import for programmatic usage, providing methods like `create`, `router`, and `defaults`.

create, router, defaults

✓ import jsonServer from 'json-server'; const server = jsonServer.create();

✗ import { create, router, defaults } from 'json-server';

These methods are properties of the default `jsonServer` import, not direct named exports.

CLI

✓ npx json-server db.json

✗ node json-server db.json

The `npx` command is the recommended way to execute JSON-Server without global installation, using the version installed in `node_modules`.

Demonstrates how to start JSON Server programmatically with a `db.json` file, applying default middleware, adding a custom route, and listening on port 3000.

import jsonServer from 'json-server'; import path from 'path'; const server = jsonServer.create(); const router = jsonServer.router(path.join(__dirname, 'db.json')); const middlewares = jsonServer.defaults(); // Set default middlewares (logger, static, cors and no-cache) server.use(middlewares); // Add custom routes before JSON Server router server.get('/echo', (req, res) => { res.json(req.query); }); server.use(router); server.listen(3000, () => { console.log('JSON Server is running on http://localhost:3000'); }); // Example db.json content // { // "posts": [ { "id": "1", "title": "json-server", "author": "typicode" } ] // }

json-server --version

Debug

Known issues

breakingVersion 1.x is currently in beta. Expect frequent breaking changes and API adjustments before the stable release. Functionality and behaviors may change without prior notice.

fix

Refer to the latest changelog and documentation for `v1.x` updates. For a stable version, consider `v0.17.4`.

affects: >=1.0.0-beta.0

breakingQuery parameters `_start`, `_end`, and `_limit` have been dropped in `v1.0.0-beta.6` in favor of a new `_where` filtering operator and standard `_page`, `_limit` for pagination.

fix

Refactor existing queries to use `_where` for advanced filtering and standard `_page`, `_limit` parameters for pagination. For example, use `_page=1&_limit=10` instead of `_start=0&_end=10`.

affects: >=1.0.0-beta.6

breakingResource IDs generated by the server now use `base64url` random IDs instead of incremental numbers, and client-provided IDs for new resources are ignored.

fix

Do not rely on incremental numeric IDs; treat IDs as opaque strings. When creating new resources (POST), omit the `id` field from the request body or be aware it will be ignored in favor of a server-generated ID.

affects: >=1.0.0-beta.14

gotchaJSON-Server now supports both `db.json` and `db.json5` files. When using `.json` files, strict JSON parsing is applied, and invalid syntax will cause errors.

fix

Use the `.json5` extension for files formatted with JSON5 syntax. For `.json` files, ensure strict JSON validity. `json-server` can automatically insert a `$schema` reference upon startup if missing.

affects: >=1.0.0-beta.5

Errors

Common errors & fixes

Invalid JSON request body

Sending malformed JSON in POST/PUT/PATCH requests to the server.

fix

Ensure your request body is valid JSON. Since `v1.0.0-beta.13`, `json-server` returns a `400 Bad Request` error for invalid JSON bodies, providing clearer feedback.

404 Not Found response is plain text, not JSON.

Prior to `v1.0.0-beta.15`, 404 error responses were returned as plain text by default.

fix

Update `json-server` to `v1.0.0-beta.15` or newer. This version fixes the behavior to return JSON responses for 404 errors, aligning with typical API expectations.

Client-provided ID is not honored when creating a new resource (POST).

Since `v1.0.0-beta.14`, `json-server` ignores client-provided `id` fields in POST requests and generates its own unique `base64url` ID.

fix

Remove the `id` field from the request body when creating new resources via POST. Rely on the server to generate and return the `id` in the response for the newly created resource.

Upgrade

Version history

0.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/typicode/json-server ↗

packagehttps://www.npmjs.com/package/json-server ↗

homepagehttps://json-server.org ↗