@adhix11/mock-api-kit

Local-first mock API server for JavaScript and TypeScript development.
Start a mock REST API in seconds from JSON config, OpenAPI specs, or auto-generated fake data.
No cloud, no external APIs, no telemetry.

Why?

Frontend is ready but backend is not? API is down, unstable, or not yet built?

npx @adhix11/mock-api-kit start

Now your frontend can call http://localhost:4000/users, http://localhost:4000/incidents, etc — instantly, offline, with zero setup.

| Developer Pain | How mock-api-kit Helps | |---|---| | Backend not ready | Start mock API instantly | | API returns empty data | Generate fake records | | Need demo data | Seed mock data from config | | Need error scenarios | Simulate 401, 403, 500 | | Need slow API | Add latency simulation | | Need pagination | Built-in page/limit support | | Need CRUD testing | Auto-create GET/POST/PUT/PATCH/DELETE | | Need exact response shape | Custom route templates | | Need offline development | Runs fully local |

Quick Start

1. Initialize

npx @adhix11/mock-api-kit init

Creates mock-api.config.json and mock-data/ with sample data.

2. Start

npx @adhix11/mock-api-kit start

Output:

⚡ Mock API Kit running at http://localhost:4000
   Dashboard: http://localhost:4000/__mock
   Routes: 15 endpoints registered

3. Use

// Your frontend code
const users = await fetch("http://localhost:4000/users").then(r => r.json());
const user = await fetch("http://localhost:4000/users/1").then(r => r.json());

await fetch("http://localhost:4000/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Test", email: "[email protected]" })
});

Installation

# Use with npx (no install needed)
npx @adhix11/mock-api-kit start

# Or install as dev dependency
npm install -D @adhix11/mock-api-kit

CLI Commands

| Command | Description | |---|---| | mock-api-kit start | Start the mock API server | | mock-api-kit init | Scaffold config and sample data | | mock-api-kit create <resource> | Add a record with custom fields (with upsert) | | mock-api-kit generate <resource> | Generate fake data for a resource | | mock-api-kit routes | List all configured routes | | mock-api-kit report | Generate configuration report |

Start Options

mock-api-kit start [options]

  -p, --port <port>           Server port (default: 4000)
  -l, --latency <ms>          Global response latency in ms
  -c, --config <path>         Path to config file
  -s, --spec <path>           Path to local OpenAPI 3.x spec
  --force-error <status>      Force all requests to return this error

Create Options

Add records to your resource files easily from the command line:

# Add a new user (automatically assigns ID)
mock-api-kit create users name="Arun Kumar" email="[email protected]" role="admin"

# Upsert (update/merge) an existing user instead of creating a duplicate
# (If record with ID exists, it merges fields leaving other fields intact)
mock-api-kit create users id=1 status="active"

# Add multiple records via inline JSON array
mock-api-kit create users --json '[{"id": 2, "name": "Priya"}, {"id": 3, "name": "Rahul"}]'

Generate Options

Generate multiple fake data records in seconds.

By default, neither --fields nor --count is required:

• If no count is specified, it defaults to 30.
• If no fields are specified, it automatically falls back to the resource schema defined in mock-api.config.json. If no config exists, it defaults to a general schema: id, name, email, status, createdAt.

Here are the command examples for all scenarios:

# 1. Zero-config / Fallback (Generates 30 records with default schema)
mock-api-kit generate users

# 2. Positional fields (Generates 30 records with custom schema)
mock-api-kit generate incident id,name,description

# 3. Custom count & fields (Generates 50 records)
mock-api-kit generate users id,name,email,phone --count 50

# 4. Typed generator fields (Generates 100 records)
mock-api-kit generate orders title:title,amount:number,status:word --count 100

# 5. Generate seed data from local OpenAPI spec file (JSON or YAML)
mock-api-kit generate incident --spec ./openapi.json

Configuration

Create mock-api.config.json in your project root:

Simple Routes Mode

{
  "port": 4000,
  "latency": 300,
  "routes": {
    "GET /users": {
      "response": [
        { "id": 1, "name": "Arun", "email": "[email protected]", "role": "admin" },
        { "id": 2, "name": "Priya", "email": "[email protected]", "role": "user" }
      ]
    },
    "POST /users": {
      "status": 201,
      "response": {
        "id": "{{autoId}}",
        "message": "User created successfully"
      }
    }
  }
}

Auto-CRUD Resources Mode

{
  "resources": {
    "users": [
      { "id": 1, "name": "Arun" },
      { "id": 2, "name": "Priya" }
    ],
    "incidents": [
      { "id": 1, "title": "Near miss", "status": "open" }
    ]
  }
}

Auto-generates for each resource:

| Method | Path | Description | |---|---|---| | GET | /users | List all (with pagination, search, filter, sort) | | GET | /users/:id | Get single record | | POST | /users | Create or upsert record (merges fields if id duplicate is found) | | PUT | /users/:id | Full update | | PATCH | /users/:id | Partial update | | DELETE | /users/:id | Delete record |

Schema-Based Fake Data

{
  "resources": {
    "users": {
      "count": 20,
      "schema": {
        "id": "number",
        "name": "name",
        "email": "email",
        "phone": "phone",
        "createdAt": "date"
      }
    }
  }
}

Supported Schema Types

| Type | Generates | |---|---| | number / integer | Random integer | | name | Full name | | firstName / lastName | First/last name | | email | Email address | | phone | Phone number | | date | ISO date string | | text / string / sentence | Lorem sentence | | paragraph | Lorem paragraph | | word / title | Words | | boolean | true/false | | uuid | UUID v4 | | address | Street address | | city / country / zipCode | Location data | | company | Company name | | url | URL | | image / avatar | Image URL | | color | Color name |

Features

Pagination

GET /users?page=1&limit=10
GET /users?_page=1&_limit=10

Response:

{
  "data": [...],
  "page": 1,
  "limit": 10,
  "total": 50,
  "totalPages": 5
}

Without pagination params, returns a flat array.

Search

GET /users?search=arun

Searches across all string fields.

Filter

GET /users?role=admin
GET /incidents?status=open

Sort

GET /users?sort=name&order=asc
GET /incidents?sort=createdAt&order=desc

Latency Simulation

# Global
mock-api-kit start --latency 1000

# Per route in config
{
  "routes": {
    "GET /users": {
      "latency": 1200,
      "response": []
    }
  }
}

Error Simulation

# Force all requests to return 401
mock-api-kit start --force-error 401

Per-route error rate:

{
  "routes": {
    "GET /users": {
      "errorRate": 20,
      "error": {
        "status": 500,
        "response": { "message": "Internal server error" }
      },
      "response": []
    }
  }
}

20% of requests return 500.

Response Templates

{
  "routes": {
    "POST /incidents": {
      "status": 201,
      "response": {
        "id": "{{autoId}}",
        "title": "{{body.title}}",
        "status": "created",
        "createdAt": "{{now}}"
      }
    }
  }
}

| Template | Description | |---|---| | {{autoId}} | Auto-incrementing ID | | {{now}} | Current ISO timestamp | | {{body.field}} | Value from request body | | {{param.field}} | URL parameter value | | {{query.field}} | Query string value |

Auth Simulation

Simple Bearer Token

{
  "auth": {
    "enabled": true,
    "type": "bearer",
    "token": "dev-token"
  }
}

Requests without Authorization: Bearer dev-token return 401.

User Login with Roles

{
  "auth": {
    "enabled": true,
    "users": [
      { "username": "admin", "password": "admin123", "role": "admin" },
      { "username": "user", "password": "user123", "role": "user" }
    ]
  },
  "routes": {
    "DELETE /users/:id": {
      "roles": ["admin"]
    }
  }
}

Endpoints:

POST /auth/login   → { token, user }
GET  /auth/me      → current user info

File Upload Mock

Default upload endpoint at POST /upload. Add more:

{
  "uploads": ["/documents/upload", "/evidence"]
}

Response:

{
  "fileId": "file_1001",
  "filename": "photo.jpg",
  "mimetype": "image/jpeg",
  "size": 12345,
  "url": "/mock-files/file_1001.jpg",
  "message": "File uploaded successfully"
}

OpenAPI Mode

mock-api-kit start --spec ./openapi.json

Reads a local OpenAPI 3.x spec (JSON or YAML), generates routes with fake response data automatically.

Request Logging Dashboard

Open http://localhost:4000/__mock to see:

• Total request count
• Average response time
• Error rate
• Last 50 requests with method, path, status, duration
• Expandable request/response bodies
• All configured routes

Health Check

GET /__health → { status: "ok", uptime, routes, resources }

Programmatic API

import { createMockServer } from "@adhix11/mock-api-kit";

const server = createMockServer({
  port: 4000,
  latency: 0,
  resources: {
    users: [
      { id: 1, name: "Arun", email: "[email protected]" }
    ]
  },
  routes: {
    "GET /api/status": {
      response: { status: "ok", timestamp: "{{now}}" }
    }
  }
});

await server.start();

// Later...
await server.stop();

Exports

import {
  createMockServer,    // Server factory
  DataStore,           // In-memory data store
  generateRecords,     // Fake data generator
  processTemplate,     // Template engine
  loadConfig,          // Config file loader
} from "@adhix11/mock-api-kit";

Full Config Reference

{
  "port": 4000,
  "latency": 0,

  "routes": {
    "METHOD /path": {
      "status": 200,
      "response": {},
      "latency": 0,
      "errorRate": 0,
      "error": { "status": 500, "response": {} },
      "roles": ["admin"]
    }
  },

  "resources": {
    "resourceName": [
      { "id": 1, "field": "value" }
    ],
    "generatedResource": {
      "count": 20,
      "schema": {
        "id": "number",
        "name": "name",
        "email": "email"
      }
    }
  },

  "auth": {
    "enabled": true,
    "type": "bearer",
    "token": "dev-token",
    "users": [
      { "username": "admin", "password": "admin123", "role": "admin" }
    ]
  },

  "uploads": ["/documents/upload"]
}

Tech Stack

• Express — HTTP server
• Commander — CLI framework
• @faker-js/faker — Fake data generation
• picocolors — Terminal colors
• multer — File upload handling
• yaml — OpenAPI YAML parsing
• TypeScript — Full type safety

Philosophy

• 🔒 100% local — No cloud, no external APIs
• 🚫 No telemetry — Zero data collection
• ⚡ Zero config — Works out of the box
• 🎯 Daily driver — Built for everyday development
• 📦 Lightweight — Minimal dependencies

License

MIT © adhix11