@webmasterdevlin/json-server

A TypeScript implementation of json-server with additional features and comprehensive TypeScript types.

Features

• Full TypeScript support with comprehensive type definitions
• RESTful API endpoints from a JSON file or JavaScript object
• API prefix support - Access all routes with /api/* prefix for production-like experience
• Configurable routes with custom route definitions
• Multiple package managers support (npm, yarn, pnpm, bun)
• CORS support with configurable options
• Delay simulation for network latency testing
• Read-only mode for safe demonstrations
• Static file serving for frontend assets
• Custom middleware support for advanced use cases
• Deno compatibility for modern runtime support
• Beautiful CLI interface with color-coded outputs and intuitive feedback
• Comprehensive pagination with flexible query parameters
• Advanced filtering and sorting capabilities

Installation

Using npm

npm install @webmasterdevlin/json-server

Using yarn

yarn add @webmasterdevlin/json-server

Using pnpm

pnpm add @webmasterdevlin/json-server

Using bun

bun add @webmasterdevlin/json-server

Quick Start

CLI Usage

Create a db.json file:

{
  "posts": [{ "id": 1, "title": "json-server", "author": "webmasterdevlin" }],
  "comments": [{ "id": 1, "body": "some comment", "postId": 1 }],
  "profile": { "name": "webmasterdevlin" }
}

Start the JSON Server:

npx json-server db.json

Or with API prefix support (enables /api/* routes):

npx json-server db.json --enable-api-prefix

Or use it from your package.json scripts:

{
  "scripts": {
    "mock-api": "json-server db.json",
    "mock-api-with-prefix": "json-server db.json --enable-api-prefix"
  }
}

Now if you go to http://localhost:3000/posts/1, you'll get:

{ "id": 1, "title": "json-server", "author": "webmasterdevlin" }

With API prefix enabled, you can also access the same data at http://localhost:3000/api/posts/1.

API Usage

import { create } from '@webmasterdevlin/json-server';

// Create a server with custom options
const server = create({
  port: 3001,
  host: 'localhost',
  delay: 500, // Add 500ms delay to all responses
});

// Load database from file
server.loadDatabase('./db.json');

// Start the server
server.start().then(() => {
  console.log('Server is running at http://localhost:3001');
});

Deno Usage

// Import from URL or local file
import { create } from 'npm:@webmasterdevlin/json-server';
// OR use the mod.ts entry point
// import { create } from "./mod.ts";

const server = create({
  port: 8000,
  host: 'localhost',
});

// Load database from file
server.loadDatabase('./db.json');

// Start the server
await server.start();

Routes

All HTTP methods are supported:

GET    /posts
GET    /posts/1
POST   /posts
PUT    /posts/1
PATCH  /posts/1
DELETE /posts/1

Custom Routes

Create a routes.json file:

{
  "/api/*": "/$1",
  "/blog/:id": "/posts/:id",
  "/blog/:category/:title": "/posts?category=:category&title=:title"
}

Start the server with custom routes:

json-server db.json --routes routes.json

Now you can access your resources with:

/api/posts
/api/posts/1
/blog/1
/blog/javascript/typescript-basics

Command Line Options

Usage:
  json-server [options] <source>

Options:
  --port, -p         Set port                                  [default: 3000]
  --host, -H         Set host                          [default: "localhost"]
  --watch, -w        Watch for changes                        [default: false]
  --routes, -r       Path to routes file                               [string]
  --middlewares, -m  Path to middlewares files                          [array]
  --static, -s       Path to static files                               [array]
  --read-only, --ro  Allow only GET requests                  [default: false]
  --no-cors, --nc    Disable CORS                             [default: false]
  --no-gzip, --ng    Disable GZIP compression                 [default: false]
  --enable-api-prefix, --api  Enable /api/* prefix routes     [default: false]
  --delay, -d        Add delay to responses (ms)                       [number]
  --id, -i           Set database id field                     [default: "id"]
  --foreignKeySuffix Set foreign key suffix               [default: "_id"]
  --quiet, -q        Suppress log messages                    [default: false]
  --help, -h         Show help                                        [boolean]
  --version, -v      Show version                                     [boolean]

Example Commands

# Basic usage
json-server db.json

# With API prefix support
json-server db.json --enable-api-prefix

# Custom port with API prefix
json-server db.json --port 3001 --api

# With delay and API prefix
json-server db.json --delay 1000 --enable-api-prefix

# With custom routes and API prefix
json-server db.json --routes routes.json --api

# Read-only mode with API prefix
json-server db.json --read-only --enable-api-prefix

Filtering and Pagination

Use query parameters for filtering:

GET /posts?title=json-server&author=webmasterdevlin
GET /posts?id=1&id=2

Pagination and sorting:

GET /posts?_page=1&_limit=10
GET /posts?_sort=title&_order=asc
GET /posts?_sort=title&_order=desc

API Prefix

The API prefix feature allows you to access all your resources with an /api prefix, making your mock API feel more like a production backend. When enabled, both standard routes and API-prefixed routes work simultaneously.

Why Use API Prefix?

• Production-like experience: Makes your mock API behave like a real backend with /api routes
• Frontend framework compatibility: Works seamlessly with frameworks that expect API routes to start with /api
• Route organization: Helps differentiate API routes from static file routes
• Development consistency: Matches common backend API patterns

Using API Prefix with CLI

Enable the API prefix feature using the --enable-api-prefix (or --api shorthand) flag:

json-server db.json --enable-api-prefix

Both route styles work simultaneously:

# Standard routes (still work)
curl http://localhost:3000/posts
curl http://localhost:3000/posts/1
curl http://localhost:3000/db

# API-prefixed routes (also work)
curl http://localhost:3000/api/posts
curl http://localhost:3000/api/posts/1
curl http://localhost:3000/api/db

All HTTP Methods Supported

The API prefix works with all HTTP methods:

# GET requests
GET /api/posts
GET /api/posts/1

# POST requests
POST /api/posts
Content-Type: application/json
{"title": "New Post", "author": "John Doe"}

# PUT requests
PUT /api/posts/1
Content-Type: application/json
{"id": 1, "title": "Updated Post", "author": "John Doe"}

# PATCH requests
PATCH /api/posts/1
Content-Type: application/json
{"title": "Partially Updated Post"}

# DELETE requests
DELETE /api/posts/1

Query Parameters and Pagination

All query parameters work with the API prefix:

# Filtering
GET /api/posts?author=webmasterdevlin
GET /api/posts?title=json-server&author=webmasterdevlin

# Pagination
GET /api/posts?_page=1&_limit=10
GET /api/posts?_page=2&_limit=5

# Sorting
GET /api/posts?_sort=title&_order=asc
GET /api/posts?_sort=id&_order=desc

# Pagination endpoint
GET /api/posts/paginate?_page=1&_limit=10

Using API Prefix Programmatically

import { create } from '@webmasterdevlin/json-server';

const server = create({
  port: 3000,
  enableApiPrefix: true, // Enable the API prefix feature
});

server.loadDatabase('./db.json');
server.start().then(() => {
  console.log('Server running with API prefix support');
  console.log('Access your API at:');
  console.log('- http://localhost:3000/posts (standard)');
  console.log('- http://localhost:3000/api/posts (with prefix)');
});

Example with Custom Routes

When using custom routes with API prefix enabled:

routes.json:

{
  "/api/profile": {
    "GET": "/users/1"
  },
  "/api/featured-post": {
    "GET": "/posts/1"
  },
  "/api/users/:id/posts": {
    "GET": "/posts?userId=:id"
  }
}

Start server:

json-server db.json --routes routes.json --enable-api-prefix

Access routes:

curl http://localhost:3000/api/profile
curl http://localhost:3000/api/featured-post
curl http://localhost:3000/api/users/1/posts

Programmatic Usage

Basic Usage

import { create } from '@webmasterdevlin/json-server';

// Database object
const data = {
  posts: [{ id: 1, title: 'json-server', author: 'webmasterdevlin' }],
  comments: [{ id: 1, body: 'some comment', postId: 1 }],
};

// Create server
const server = create({
  port: 3000,
  host: 'localhost',
  readOnly: false, // Allow all HTTP methods
  delay: 1000, // Add 1s delay to responses
  enableApiPrefix: true, // Enable /api/* prefix for all routes
});

// Create a custom route
server.addRoute('/custom-route', 'GET', (req, res) => {
  res.json({ message: 'This is a custom route' });
});

// Start server
server.loadDatabase('./db.json');
server.start().then(() => {
  console.log('JSON Server is running');
  console.log('Standard routes: http://localhost:3000/posts');
  console.log('API routes: http://localhost:3000/api/posts');
});

Configuration Options

interface ServerOptions {
  port: number; // Server port (default: 3000)
  host: string; // Server host (default: 'localhost')
  cors: boolean; // Enable CORS (default: true)
  static: string | string[]; // Static file paths
  middlewares: RequestHandler[]; // Custom middlewares
  bodyParser: boolean; // Enable body parsing (default: true)
  noCors: boolean; // Disable CORS (default: false)
  noGzip: boolean; // Disable gzip (default: false)
  delay: number; // Response delay in ms (default: 0)
  quiet: boolean; // Suppress logs (default: false)
  readOnly: boolean; // Read-only mode (default: false)
  enableApiPrefix: boolean; // Enable /api/* routes (default: false)
}

Beautiful CLI Experience

One of the standout features of this implementation is the beautifully styled CLI interface, designed to make your development experience more enjoyable and informative.

Server Status Display

When you start the server, you'll see a beautiful status banner with:

🚀 JSON Server is running

 http://localhost:3000 - API Root
 http://localhost:3000/db - Full Database

 Read Only: No
 API Prefix: Enabled
 CORS: Enabled

 ℹ️ Press Ctrl+C to stop the server

Color-Coded Messages

All CLI messages are color-coded for better readability:

• 🟢 Green for success messages
• 🔵 Blue for informational messages
• 🟡 Yellow for warnings
• 🔴 Red for errors

Visual Feedback for Key Events

💾 Database loaded: db.json (3 collections, 20 items)
🔀 Loaded 4 custom routes from routes.json
👀 Watching for changes: db.json

Beautiful Help Display

The help command (json-server --help) provides a well-organized and colorful display of all available options:

⚡️ @webmasterdevlin/json-server ⚡️
A TypeScript-powered REST API mock server

Usage:
json-server [options] <source>

Options:
  --port, -p         Set port                                  [default: 3000]
  --host, -H         Set host                          [default: "localhost"]
  # ...more options...

Examples:
  json-server db.json
  json-server db.json --port 3001
  # ...more examples...

Try It Yourself!

Experience the beautiful CLI interface by installing and running json-server:

npm install @webmasterdevlin/json-server
npx json-server db.json

Development

Prerequisites

• Node.js (v16.0.0 or higher)
• npm, yarn, pnpm, or bun

Setup

# Clone the repository
git clone https://github.com/webmasterdevlin/json-server.git
cd json-server

# Install dependencies
npm install

# Run development server
npm run dev

# Run tests
npm test

# Build for production
npm run build

Real-World Examples

Frontend Development with API Prefix

When developing a React/Vue/Angular application that will eventually connect to a backend API with /api routes:

# Start json-server with API prefix
json-server db.json --enable-api-prefix --port 3001

# Your frontend can now make requests to:
# http://localhost:3001/api/users
# http://localhost:3001/api/posts
# http://localhost:3001/api/comments

Frontend code example:

// This will work with both your mock server and production API
const response = await fetch('/api/users');
const users = await response.json();

Testing Different Network Conditions

# Simulate slow network
json-server db.json --api --delay 2000

# Test with different delays
json-server db.json --api --delay 500   # 500ms delay
json-server db.json --api --delay 1500  # 1.5s delay

Safe Demo Mode

# Read-only mode with API prefix for demos
json-server db.json --api --read-only

# Only GET requests will work, perfect for demonstrations

Contributing

Please read our Contributing Guide and Code of Conduct before submitting a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

This project is inspired by the original json-server by webmasterdevlin, rewritten in TypeScript with additional features and improvements.