# json-server > [![Node.js CI](https://github.com/typicode/json-server/actions/workflows/node.js.yml/badge.svg)](https://github.com/typicode/json-server/actions/workflows/node.js.yml) Latest version **1.0.0-beta.15** (published 2026-03-23) · MIT license · 0 weekly downloads ## Install ```sh npm install json-server pnpm add json-server yarn add json-server bun add json-server ``` Provides the command `json-server`. ## Health **Score 73/100 (B)** — status: active. Positive: has types package; esm support; no vulnerabilities; has provenance; high quality score; popular repo; extremely popular. Warnings: low downloads. ## Facts | | | |---|---| | Version | 1.0.0-beta.15 | | Published | 2026-03-23 | | First published | 2013-12-03 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | separate (@types/json-server) | | Module format | ESM | | Node | >=22.12.0 | | Dependencies | 13 | | Unpacked size | 38.1 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 75705 | | Author | typicode | | Maintainers | typicode | | Keywords | JSON, server, fake, REST, API, prototyping, mock, mocking, test, testing, rest, data, dummy | ## Links - npm: https://www.npmjs.com/package/json-server - Repository: https://github.com/typicode/json-server - Homepage: https://github.com/typicode/json-server#readme - Issues: https://github.com/typicode/json-server/issues - npm.io page: https://npm.io/package/json-server ## Dependencies (13) - [eta](https://npm.io/package/eta.md) ^4.5.0 - [sirv](https://npm.io/package/sirv.md) ^3.0.2 - [chalk](https://npm.io/package/chalk.md) ^5.6.2 - [json5](https://npm.io/package/json5.md) ^2.2.3 - [lowdb](https://npm.io/package/lowdb.md) ^7.0.1 - [sort-on](https://npm.io/package/sort-on.md) ^7.0.0 - [chokidar](https://npm.io/package/chokidar.md) ^5.0.0 - [dot-prop](https://npm.io/package/dot-prop.md) ^10.1.0 - [inflection](https://npm.io/package/inflection.md) ^3.0.2 - [milliparsec](https://npm.io/package/milliparsec.md) ^5.1.0 - [@tinyhttp/app](https://npm.io/package/@tinyhttp/app.md) ^3.0.1 - [@tinyhttp/cors](https://npm.io/package/@tinyhttp/cors.md) ^2.0.1 - [@tinyhttp/logger](https://npm.io/package/@tinyhttp/logger.md) ^2.1.0 ## Alternatives - [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads - [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads - [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads - [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads - [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads ## Recent versions - 1.0.0-beta.15 (latest) — 2026-03-23 - 1.0.0-beta.14 — 2026-03-20 - 1.0.0-beta.13 — 2026-03-13 - 1.0.0-beta.12 — 2026-02-28 - 1.0.0-beta.10 — 2026-02-26 - 1.0.0-beta.9 — 2026-02-19 - 1.0.0-beta.8 — 2026-02-19 - 1.0.0-beta.7 — 2026-02-19 - 1.0.0-beta.6 — 2026-02-14 - 1.0.0-beta.5 — 2026-01-22 - 1.0.0-beta.4 — 2026-01-21 - 1.0.0-beta.3 — 2024-09-24 - 1.0.0-beta.2 — 2024-08-19 - 1.0.0-beta.1 — 2024-06-04 - 1.0.0-beta.0 — 2024-05-13 - … 150 more at https://npm.io/package/json-server/versions ## README # JSON-Server [![Node.js CI](https://github.com/typicode/json-server/actions/workflows/node.js.yml/badge.svg)](https://github.com/typicode/json-server/actions/workflows/node.js.yml) > [!IMPORTANT] > Viewing beta v1 documentation – usable but expect breaking changes. For stable version, see [here](https://github.com/typicode/json-server/tree/v0.17.4) > [!NOTE] > Using React ⚛️ and tired of CSS-in-JS? See [MistCSS](https://github.com/typicode/mistcss) 👀 ## Install ```shell npm install json-server ``` ## Usage Create a `db.json` or `db.json5` file ```json { "$schema": "./node_modules/json-server/schema.json", "posts": [ { "id": "1", "title": "a title", "views": 100 }, { "id": "2", "title": "another title", "views": 200 } ], "comments": [ { "id": "1", "text": "a comment about post 1", "postId": "1" }, { "id": "2", "text": "another comment about post 1", "postId": "1" } ], "profile": { "name": "typicode" } } ```
View db.json5 example ```json5 { posts: [ { id: "1", title: "a title", views: 100 }, { id: "2", title: "another title", views: 200 }, ], comments: [ { id: "1", text: "a comment about post 1", postId: "1" }, { id: "2", text: "another comment about post 1", postId: "1" }, ], profile: { name: "typicode", }, } ``` You can read more about JSON5 format [here](https://github.com/json5/json5).
Start JSON Server ```bash npx json-server db.json ``` This starts the server at `http://localhost:3000`. You should see: ``` JSON Server started on PORT :3000 http://localhost:3000 ``` Access your REST API: ```bash curl http://localhost:3000/posts/1 ``` **Response:** ```json { "id": "1", "title": "a title", "views": 100 } ``` Run `json-server --help` for a list of options ## Sponsors ✨ ### Gold | | | :--------------------------------------------------------------------------------------------------------------------------------------------------------: | | | | | | | | tower-dock-icon-light | | ### Silver | | | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | | ### Bronze | | | | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | | | [Become a sponsor and have your company logo here](https://github.com/users/typicode/sponsorship) ## Query Capabilities JSON Server supports advanced querying out of the box: ```http GET /posts?views:gt=100 # Filter by condition GET /posts?_sort=-views # Sort by field (descending) GET /posts?_page=1&_per_page=10 # Pagination GET /posts?_embed=comments # Include relations GET /posts?_where={"or":[...]} # Complex queries ``` See detailed documentation below for each feature. ## Routes ### Array Resources For array resources like `posts` and `comments`: ```http GET /posts GET /posts/:id POST /posts PUT /posts/:id PATCH /posts/:id DELETE /posts/:id ``` ### Object Resources For singular object resources like `profile`: ```http GET /profile PUT /profile PATCH /profile ``` ## Query params ### Conditions Use `field:operator=value`. Operators: - no operator -> `eq` (equal) - `lt` less than, `lte` less than or equal - `gt` greater than, `gte` greater than or equal - `eq` equal, `ne` not equal - `in` included in comma-separated list - `contains` string contains (case-insensitive) - `startsWith` string starts with (case-insensitive) - `endsWith` string ends with (case-insensitive) Examples: ```http GET /posts?views:gt=100 GET /posts?title:eq=Hello GET /posts?id:in=1,2,3 GET /posts?author.name:eq=typicode GET /posts?title:contains=hello GET /posts?title:startsWith=Hello GET /posts?title:endsWith=world ``` ### Sort ```http GET /posts?_sort=title GET /posts?_sort=-views GET /posts?_sort=author.name,-views ``` ### Pagination ```http GET /posts?_page=1&_per_page=25 ``` **Response:** ```json { "first": 1, "prev": null, "next": 2, "last": 4, "pages": 4, "items": 100, "data": [ { "id": "1", "title": "...", "views": 100 }, { "id": "2", "title": "...", "views": 200 } ] } ``` **Notes:** - `_per_page` defaults to `10` if not specified - Invalid `_page` or `_per_page` values are automatically normalized to valid ranges ### Embed ```http GET /posts?_embed=comments GET /comments?_embed=post ``` ### Complex filter with `_where` `_where` accepts a JSON object and overrides normal query params when valid. ```http GET /posts?_where={"or":[{"views":{"gt":100}},{"author":{"name":{"lt":"m"}}}]} ``` ## Delete dependents ```http DELETE /posts/1?_dependent=comments ``` ## Static Files JSON Server automatically serves files from the `./public` directory. To serve additional static directories: ```bash json-server db.json -s ./static json-server db.json -s ./static -s ./node_modules ``` Static files are served with standard MIME types and can include HTML, CSS, JavaScript, images, and other assets. ## Migration Notes (v0 → v1) If you are upgrading from json-server v0.x, note these behavioral changes: - **ID handling:** `id` is always a string and will be auto-generated if not provided - **Pagination:** Use `_per_page` with `_page` instead of the deprecated `_limit` parameter - **Relationships:** Use `_embed` instead of `_expand` for including related resources - **Request delays:** Use browser DevTools (Network tab > throttling) instead of the removed `--delay` CLI option > **New to json-server?** These notes are for users migrating from v0. If this is your first time using json-server, you can ignore this section. --- _Source: https://npm.io/package/json-server · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._