mock-server-proxy

Lightweight local API mock + proxy server. Serves JSON files when present, otherwise proxies to the real API.

A simple local API mock server that lets you build frontends before the backend is ready, demo your app offline, and stabilize flaky endpoints during development.

Why use this?

Build frontends without waiting for backend APIs. Create mock responses instantly and switch to real APIs when they're ready.

Demo your app anywhere. Work offline, on planes, or in meetings without internet connectivity.

Stabilize flaky endpoints. Lock unreliable APIs to consistent local responses during development.

Share reproducible mocks. Version control your mock data and share with your team.

Quick Demo

# Install globally
npm i -g mock-server-proxy

# Start with example mocks
mock-server-proxy --dir ./mocks --port 5050

# Test it
curl http://localhost:5050/users/42
# → {"id":"42","name":"user-42","role":"viewer","email":"user42@example.com"}

Features

• File-based routing → mocks/users/[id].get.json → GET /users/42
• JSON-only mocks → Quick static responses or rich responses with status, headers, delay
• Proxy fallback → Unmocked routes go to real API
• Record mode → Auto-save real responses as JSON mocks
• Latency injection → Simulate slow networks
• Dynamic params → Use {{id}} in responses, filled from URL/query
• No setup → One binary / npx, works instantly
• File watching → Hot reload mocks without restart

Quick Start

Install

npm i -g mock-server-proxy

Run with mocks only

mock-server-proxy --dir ./mocks --port 5050

Run with proxy and record

mock-server-proxy --dir ./mocks --port 5050 --proxy https://api.example.com --record

Use without install

npx mock-server-proxy --dir ./mocks --port 5050 --proxy https://api.example.com

Examples

Basic Mock

mocks/users/[id].get.json:

{
  "headers": { "x-source": "mock" },
  "delay": 100,
  "body": { "id": "{{id}}", "name": "user-{{id}}" }
}

curl http://localhost:5050/users/42
# → { "id": "42", "name": "user-42" }

Authentication Mock

mocks/auth/login.post.json:

{
  "status": 201,
  "headers": { "x-auth-token": "mock-jwt-token" },
  "body": { 
    "token": "abc123", 
    "user": { "id": 1, "name": "rhea" } 
  }
}

Search with Query Params

mocks/search.get.json:

{
  "body": {
    "query": "{{q}}",
    "results": [
      { "id": 1, "title": "Search result for {{q}}" }
    ]
  }
}

curl "http://localhost:5050/search?q=hello"
# → { "query": "hello", "results": [...] }

Wildcard Routes

mocks/feed/[...rest].get.json:

{
  "body": {
    "path": "{{rest}}",
    "feed_items": [...]
  }
}

curl http://localhost:5050/feed/posts/123/comments
# → { "path": "posts/123/comments", "feed_items": [...] }

CLI Options

Option	Description	Default
--dir <path>	Mocks directory	required
--port <number>	Local server port	5050
--proxy <url>	Real API base URL	none
--record	Save proxy responses as mocks	false
--latency <ms>	Global artificial delay	0
--verbose	Verbose logging	false
--watch	Watch for file changes	false

File Structure

mocks/
├── _config.json              # Global defaults
├── users/
│   ├── _config.json          # Folder defaults
│   ├── [id].get.json         # GET /users/:id
│   └── list.get.json         # GET /users/list
├── auth/
│   └── login.post.json       # POST /auth/login
└── search.get.json           # GET /search

Configuration

Global Config

mocks/_config.json:

{
  "latency": 200,
  "headers": { "cache-control": "no-store" }
}

Folder Config

mocks/users/_config.json:

{
  "latency": 80,
  "headers": { "x-api-version": "v1" }
}

Mock File Format

Simple Response

{ "id": 1, "name": "rhea" }

Defaults: status 200, no extra headers, no delay.

Rich Response

{
  "status": 201,
  "headers": { "x-mock": "sidecar" },
  "delay": 250,
  "body": { "ok": true, "id": 42 }
}

Proxy Mode

When no mock file exists and --proxy is set, requests are forwarded to the real API:

mock-server-proxy --dir ./mocks --port 5050 --proxy https://api.example.com

Record Mode

Automatically save real API responses as mock files:

mock-server-proxy --dir ./mocks --port 5050 --proxy https://api.example.com --record

Dynamic Parameters

URL Parameters

• [id].get.json → {{id}} from /users/123
• [slug].get.json → {{slug}} from /posts/my-post

Query Parameters

• {{q}} from ?q=search
• {{page}} from ?page=2
• {{limit}} from ?limit=10

Wildcard Parameters

• [...rest].get.json → {{rest}} from /feed/a/b/c

Use Cases

• Build frontends before backend is ready
• Demo your app offline
• Lock flaky endpoints to stable responses
• Share reproducible mocks with your team
• Test error scenarios and edge cases
• Speed up development with instant responses

Testing

Run the included test script to see all features in action:

./test.sh

Development

git clone https://github.com/ridxm/mock-server-proxy.git
cd mock-server-proxy
npm install
npm link

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request