web-proxy is a reverse proxy that gives production grade structured logs to web applications that were not built with observability in mind. Many popular frameworks log inconsistently, and some production builds drop logging entirely. NextJS and Prisma ORM are typical examples. Instead of editing application code, run web-proxy in front of the application. Every request is logged as structured JSON before it is forwarded upstream, so traffic becomes queryable in Grafana, Loki, and Promtail.

What a request looks like

When a client hits the proxy, web-proxy records the full picture of the exchange.

{
  "level": "info",
  "status": 200,
  "method": "GET",
  "URI": "/api/items?page=2",
  "route": "/api/items",
  "protocol": "HTTP/1.1",
  "remote_ip": "203.0.113.8",
  "host": "example.com",
  "referer": "https://example.com/home",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
  "id": "6f9c2ab7e4d84a2f",
  "latency": 2850000,
  "latency_human": "2.85ms",
  "bytes_in": 0,
  "bytes_out": 4182,
  "target": "http://localhost:3001"
}

Every log line carries the request ID, the client IP taken from the X-Forwarded-For header, the proxy target that served the request, and latency in nanoseconds plus a human readable form. Requests whose paths carry a file extension are logged separately from application routes, which keeps static asset noise easy to filter. Failed requests produce an error level line with the same fields plus the underlying error.

Features

• Structured JSON logs for every request with status, method, path, latency, bytes transferred, request ID, and real client IP.
• Reverse proxying to a single application or load balancing across several upstreams.
• TCP or HTTP health checks that drop dead upstreams from rotation and answer 503 when every target is down.
• Static hosting for frontend builds.
• Managed mode that starts your web application and forwards public traffic to it.
• Access control through basic auth, bearer keys, a branded session login page, OpenID Connect, or any combination of these at once.
• Blocking by user agent substring or client IP and CIDR range.
• A built-in bot guard: severity tiers that score requests from curated IP/UA feeds, honeypots, header sanity, and per-IP behaviour, then block, throttle, tarpit, or serve a JS or proof-of-work challenge.
• Configuration through environment variables with safe defaults and .env support.

Run modes

Mode	Invocation	What it does
Managed app	web-proxy -app	Starts your application from package.json and proxies public traffic to it
Reverse proxy	web-proxy	Forwards PORT to an upstream application on PROXY_PORT
Load balancer	web-proxy with PROXY_TARGETS set	Distributes requests across upstreams that pass health checks
Static site	web-proxy -static	Serves the frontend build in -static-dir

Documentation

• Installation - every way to install and run web-proxy
• Usage - full environment variable and CLI flag reference
• Authentication - basic, bearer, forms, and OIDC access control
• Examples - container, load balancer, static site, and auth setups

Container deployments can wrap an existing image as middleware inside the application container or as a separate proxy container. See the container middleware and container proxy examples for those setups.

Roadmap

These items are in no particular order.

• Screenshots
• Benchmarks
• Configurable logs
• Templates

License

web-proxy is released under the Apache License 2.0.