Scenario-based local API proxy for fast frontend development and test workflows.

📖 Documentation · ⚡ Quick Start · 🔧 CLI · 💬 GitHub

Why local-proxy

• Mock only the endpoints you care about
• Keep all other traffic flowing to your real API
• Simulate delays and failures before production
• Reuse realistic fixtures without backend dependencies

# install
npm i -g @bvbmz/local-proxy

# create scenarios template
local-proxy --init

# run proxy
local-proxy --target https://api.example.com

Default local endpoint:

http://localhost:5050/api

local-proxy [options]

| Option | Description | Default | | --- | --- | --- | | -t, --target <url> | Upstream API URL | required unless --init | | -p, --port <number> | Port to listen on | 5050 | | -a, --api-prefix <path> | API path prefix | /api | | -s, --scenarios <file> | Scenarios file path | ./scenarios.json | | --init | Create starter scenarios.json | - | | -h, --help | Show help | - | | -V, --version | Show version | - |

scenarios.json

{
  "rules": [
    {
      "method": "GET",
      "match": "/v1/example",
      "enabled": true,
      "active_scenario": "success",
      "scenarios": {
        "success": { "status": 200, "json": { "message": "ok" } },
        "error": { "status": 500, "json": { "error": "Internal Error" } },
        "slow": { "status": 200, "delay": 2, "json": { "message": "slow" } },
        "fixture": { "status": 200, "file": "fixtures/example.json" }
      }
    },
    {
      "method": "GET",
      "match": "/v1/reports/monthly.pdf",
      "enabled": true,
      "active_scenario": "success",
      "scenarios": {
        "success": {
          "status": 200,
          "file": "fixtures/monthly.pdf",
          "contentType": "application/pdf",
          "headers": {
            "Content-Disposition": "attachment; filename=monthly.pdf"
          }
        }
      }
    }
  ]
}

Scenario fields

| Field | Description | Default | | --- | --- | --- | | status | HTTP status code | 200 | | json | Inline JSON response body | - | | file | Fixture file path (relative to project root) | - | | contentType | Override Content-Type header | auto-detected | | headers | Map of additional response headers | - | | delay | Delay in seconds before responding | - |

Each scenario must include at least one of json or file.

Non-JSON responses

file scenarios support any content type. Use contentType and headers to mock binary downloads, PDFs, CSVs, and images:

{ "status": 200, "file": "fixtures/report.pdf", "contentType": "application/pdf", "headers": { "Content-Disposition": "attachment; filename=report.pdf" } }

{ "status": 200, "file": "fixtures/export.csv", "contentType": "text/csv", "headers": { "Content-Disposition": "attachment; filename=export.csv" } }

{ "status": 200, "file": "fixtures/photo.png", "contentType": "image/png" }

When contentType is omitted, the type is auto-detected from the file extension. Files are served as raw buffers — binary content is never corrupted.

Development

pnpm install
pnpm lint
pnpm test
pnpm build

License

ISC