@webmasterdevlin/json-server

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

Features

• Full TypeScript support with type definitions
• RESTful API endpoints from a JSON file or JavaScript object
• Configurable routes
• Support for multiple package managers (npm, yarn, pnpm, bun)
• CORS support
• Delay simulation for network latency testing
• Read-only mode
• Static file serving
• Custom middleware support
• Deno compatibility

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 use it from your package.json scripts:

{
  "scripts": {
    "mock-api": "json-server db.json"
  }
}

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

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

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]
  --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]

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

Programmatic 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
});

// 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');
});

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

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.