json-server-lite

Description

json‑server-lite is a minimalistic, zero‑configuration CLI tool—think of it as a lightweight alternative to json‑server.
Instantly turn any JSON file into a full CRUD REST API with built‑in live reloading, automatic ID management, and robust error handling.

---

Features

• Instant REST API from JSON file
• Live reload on file changes (--watch mode)
• Automatic ID generation for new resources
• Full CRUD support (GET, POST, PUT, PATCH, DELETE)
• Color-coded request logging
• JSON syntax error handling
• cors enabled by default

---

Installation

Via npx (no global install required)

npx json‑server-lite path/to/db.json

Install locally

npm install json-server-lite

Global install

npm install -g json‑server-lite

---

Quick Start

1. Assume you have a json file in your project (e.g. db.json):

{
	"posts": [{ "id": 1, "title": "Hello World" }],
	"comments": [{ "id": 1, "body": "Nice post!" }]
}

2. Run the server:

npx json-server-lite db.json

You will see in your terminal:

✅ Data successfully loaded from db.json

Watching file for changes...

> Home: http://localhost:3000

> Resources:

e.g.
  http://localhost:3000/users (5 elements)
  http://localhost:3000/posts (10 elements)
  http://localhost:3000/comments (0 elements)

> Available methods:

GET, POST, PUT, PATCH, DELETE

Press Ctrl+C to stop the server

---

CLI Options

Flag	Description	Default
-p, --port <number>	Port for the server to listen on	3000
-w, --watch	Enable watching the JSON file for changes	true (on)
--no-watch	Disable watching the JSON file for changes	false (off)

Examples

• Run with default port and watch mode

  npx json-server-lite db.json

• Custom port

  npx json-server-lite db.json --port 4000

• Explicitly enable watch (redundant, since it's the default)

  npx json-server-lite db.json --watch

• Disable watch mode

  npx json-server-lite db.json --no-watch

• Combine options

  npx json-server-lite db.json --port 5000 --no-watch

  npx json-server-lite db.json -p 5000 -w

---

Endpoints

For each top‑level key in your JSON file (e.g. posts, comments, users), the following endpoints are automatically created:

Method	Path	Description
GET	/<resource>	Get all items of the resource
POST	/<resource>	Create a new item (ID auto‑generated)
GET	/<resource>/:id	Get a single item by ID
PUT	/<resource>/:id	Replace an item by ID
PATCH	/<resource>/:id	Update one or more fields by ID
DELETE	/<resource>/:id	Delete an item by ID

---

Error Handling

• Initial load: if db.json has syntax errors when the server first starts, the process will exit with:

❌ Initial load error: <error message>

• Live watch: if you modify db.json and introduce a syntax error, the server will:

1. Print in terminal:

   ❌ Read error: <error message>
   

2. Return HTTP 503 Service Unavailable on all requests, with JSON body:

   {
   	"error": "Service unavailable: JSON file has syntax errors. Please fix the file first."
   }

After you correct the file, it will reload automatically and resume normal operation.

---

Live Reload (Watch Mode)

By default, watch mode is on. Any time you save db.json, the server:

1. Reloads the file in memory.
2. Recomputes resource list and next IDs.
3. Prints in terminal:

✅ Data reloaded from db.json

---

Shutdown

To stop server gracefully:

1. Press Ctrl+C in terminal
2. Server will show:

🛑 Stopping server...
✅ The server has been stopped successfully.

---

Under the Hood

Core Technologies

• Express.js - Web server framework
• Commander.js - CLI interface
• Chokidar - File watching
• Chalk - Terminal styling

Architecture

• In-memory data store with disk persistence
• Dynamic route generation
• Automatic ID management
• Middleware-based request processing

Data Flow

1. Load JSON file into memory
2. Generate routes from top-level keys
3. Handle requests through middleware stack
4. Persist changes to disk on modifications