Skip to Content

upstream.ts

app/upstream.ts puts the app in front of an existing API; requests with no handler are forwarded to the real system and recorded in the traffic log.

app/ ├── upstream.ts # /api/erp → https://erp.congty.vn/api └── erp/ └── orders/ └── get.ts # replaces only GET /api/erp/orders

What it does

Use it to replace an old system (ERP, partner service) one endpoint at a time: the app takes every request, endpoints with a handler answer themselves, the rest go on to the real system. It also mocks an endpoint that isn’t ready or fakes errors to test the UI.

Order:

  • A matching app handler (method and path) always wins.
  • A request under a prefix with no handler goes to origin plus the rest of the path, keeping method, query, body and headers (except cookie, host). The longest prefix is tried first.
  • Outside every prefix, the usual 404.

Exports

default, an object or an array; each entry has:

  • prefix: the app path, with /api, e.g. "/api/erp".
  • origin: the real system’s https:// address, written as a literal.
  • auth (optional): "forward" (default) passes the user’s Authorization header on; "service" drops it and sends your headers.
  • headers (optional): headers to send, usually a service token read from env.
  • log (optional): { bodies: false } keeps bodies out of the log.

Example

app/upstream.ts
import { env } from "manh/env"; export default [ { prefix: "/api/erp", origin: "https://erp.congty.vn/api" }, { prefix: "/api/pay", origin: "https://pay.partner.vn", auth: "service", headers: { authorization: `Bearer ${env.PAY_TOKEN}` } }, ];

In a handler, upstream(c) from manh/upstream fetches the real answer for you to change, and mock(c, data, { status, delay }) answers with fake data without calling the real system.

Good to know

  • origin must be an https:// string to a public domain: no IPs, no localhost, no internal names. check reports upstream.origin-invalid; a missing origin is upstream.origin-missing.
  • APIs only. It is not a proxy for whole HTML websites.
  • Keep the real system’s token in Secrets and read it with env; never in code (code.hardcoded-secret).
  • The preview doesn’t call upstreams. Test on the deployed app.
  • Every /api request is recorded in the traffic log; headers like authorization and fields like password are masked.
  • The extension must be .ts; app/upstream.tsx is ignored (config.wrong-extension).

Next steps

Last updated