another-local-reverse-proxy

TypeScript reverse proxy for Node.js 24 LTS with a dependency-free runtime.

Features

• declarative config.json
• multiple listeners and host rules
• route selection by local listen port and optional Host header
• HTTPS/TLS termination
• WebSocket upgrade proxying
• CLI startup with a config path
• no external runtime dependencies
• Vite build output for the CLI and harness
• Vitest coverage for runtime and architectural guardrails

Usage

npm install
npm test
npm run build
node ./dist/bin/another-local-reverse-proxy.js ./config.example.json

The CLI also accepts --config:

node ./dist/bin/another-local-reverse-proxy.js --config ./config.example.json

Development workflow

npm run lint
npm run format:check
npm run format
npm run typecheck
npm run harness

Releases

• Versioning is managed with Changesets (.changeset/*.md).
• Stable releases publish from main through .github/workflows/release-main.yml.
• Prereleases publish from release/next through .github/workflows/release-prerelease.yml using npm dist-tag next.
• release/next is maintained manually, and cherry-picks are allowed.
• Publishing is workflow-only and gated by a passing CI job.

Create a changeset when a change should be released:

npm run changeset

Configuration shape

{
  "listeners": [
    {
      "port": 8080,
      "protocol": "http"
    },
    {
      "port": 8443,
      "protocol": "https",
      "tls": {
        "keyPath": "./certs/localhost.key",
        "certPath": "./certs/localhost.crt"
      }
    }
  ],
  "routes": [
    {
      "match": {
        "listenPort": 8080,
        "host": "app.local"
      },
      "upstream": {
        "protocol": "http",
        "host": "127.0.0.1",
        "port": 3000
      }
    }
  ]
}

Notes

• Exact host matches win over a port-only fallback route on the same listener.
• HTTPS listeners require readable keyPath and certPath files.
• WebSocket proxying uses native HTTP upgrade handling and raw socket piping.
• Production runtime code stays limited to Node.js built-ins; TypeScript, Vite, and Vitest are dev-only tooling.
• npm publish artifacts are restricted via package.json#files to exclude harness/ and agent-related files.