locagate

Tiny, file-configurable local API gateway. YAML config, prefix path routing, optional JWT. One command, zero setup.

npx locagate ./config.yaml
pnpm dlx locagate ./config.yaml

Usage

Create a locagate.yaml:

listen: "0.0.0.0:5000"
jwt:
  enabled: true
  secret: "$JWT_SECRET"
  passthrough: false
routes:
  - match: "/v1/core/*"
    target: "http://localhost:3000"
  - match: "/*"
    target: "http://localhost:3003"

Run it:

npx locagate ./locagate.yaml

Or install globally:

npm install -g locagate
locagate ./locagate.yaml

Configuration reference

| Key | Type | Default | Description | |-----|------|---------|-------------| | listen | string | "0.0.0.0:5000" | Address + port to bind | | jwt.enabled | bool | false | Enable JWT verification | | jwt.secret | string | — | HMAC secret ($VAR / ${VAR:-default} expands env vars) | | jwt.passthrough | bool | false | Allow unauthenticated requests through | | jwt.exclude | string[] | [] | Path prefixes that skip JWT | | routes | array | — | Route table (first match wins) |

Environment variable expansion works in jwt.secret and route target fields.

Route matching

| Pattern | Matches | |---------|---------| | /* | All paths (catch-all) | | /v1/core/* | /v1/core/... and /v1/core | | /health | Only /health |

How it works

1. Reads your YAML config (first argument, or ./locagate.yaml)
2. Expands $VAR / ${VAR:-default} from environment variables
3. For each incoming request, walks the route table top-to-bottom
4. First match wins — proxies to target via Node's http.request
5. WebSocket upgrade requests (e.g., Next.js HMR) are proxied transparently
6. JWT verification via HS256, x-gateway-user header injected on success

Files

bin/locagate.js         — CLI entrypoint (what npx runs)
src/index.ts            — HTTP server, routing, proxying, JWT check
src/config.ts           — YAML/JSON config loading with $VAR expansion
src/router.ts           — prefix-based route matching
src/jwt.ts              — HS256 JWT verification
locagate.yaml.sample    — annotated example config