nextjs-proxy

1# pnpm
2pnpm add nextjs-proxy
3
4# npm
5npm install nextjs-proxy
6
7# yarn
8yarn add nextjs-proxy

1// app/api/proxy/route.ts
2import { nextProxyHandler } from "nextjs-proxy"
3
4export const POST = nextProxyHandler({
5  baseUrl: "https://api.my-service.com",
6  allowOrigins: ["https://app.my-domain.com"],
7  inMemoryRate: { windowMs: 60_000, max: 100 },
8})

1// The client always POSTs a JSON body. Shape:
2//   { method, endpoint, data?, route? }
3// Prefer { route } so the server owns the destination.
4
5// Named route (recommended):
6await fetch("/api/proxy", {
7  method: "POST",
8  headers: { "content-type": "application/json" },
9  body: JSON.stringify({ route: "profile", method: "GET" }),
10})
11
12// Relative endpoint (resolved via baseUrl):
13await fetch("/api/proxy", {
14  method: "POST",
15  headers: { "content-type": "application/json" },
16  body: JSON.stringify({ method: "POST", endpoint: "/orders", data: { sku: "X1" } }),
17})

1export const POST = nextProxyHandler({
2  // Guards run top-to-bottom BEFORE the upstream fetch.
3  // The first one that fails short-circuits with its status.
4  auth: (req) => Boolean(req.headers.get("authorization")),   // 401
5  csrf: (req) => req.headers.get("x-csrf") === process.env.CSRF, // 403
6  // CORS origin check (allowOrigins) ............................ 403
7  inMemoryRate: { windowMs: 60_000, max: 100 },               // 429
8  rateLimit: async (req) => myRedisLimiter.check(req),        // 429
9  validate: async (req) => userCanAccess(req),                // 401
10  // SSRF host check on the resolved endpoint ................... 403
11})

1// app/api/proxy/route.ts
2export const POST = nextProxyHandler({
3  // The client sends { route: "profile" } — never a URL.
4  routes: {
5    profile: "https://api.my-service.com/v1/me",
6    billing: "https://billing.internal/v2/invoices",
7  },
8  allowOrigins: ["https://app.my-domain.com"],
9})
10
11// Client
12await fetch("/api/proxy", {
13  method: "POST",
14  body: JSON.stringify({ route: "profile" }),
15})

1export const POST = nextProxyHandler({
2  // Allowlist of destination hosts for absolute endpoints.
3  allowedHosts: ["api.stripe.com", "*.my-service.com"],
4
5  // Block internal / loopback / metadata hosts (default: false).
6  allowPrivateHosts: false,
7})
8// Absolute endpoints outside the allowlist -> 403 "Endpoint not allowed"

1export const POST = nextProxyHandler({
2  // Required: explicit allowlist (never "*") when using credentials.
3  allowOrigins: ["https://app.my-domain.com"],
4
5  // Emits Access-Control-Allow-Credentials: true and reflects the origin.
6  corsCredentials: true,
7})

1import { nextProxyHandler, InMemoryRateLimitStore } from "nextjs-proxy"
2
3export const POST = nextProxyHandler({
4  inMemoryRate: {
5    windowMs: 60_000,
6    max: 100,
7    key: (req) => req.headers.get("x-api-key") ?? "anon",
8    // Plug a shared backend (e.g. Redis) for global limits:
9    // store: new RedisRateLimitStore(),
10  },
11})

1export const POST = nextProxyHandler({
2  baseUrl: process.env.LLM_API_BASE,
3  // true | "auto" | (req) => boolean | "auto"
4  stream: "auto", // pipe only when upstream Content-Type is stream-like
5})
6// All guards (auth, CSRF, CORS, rate limit, validate, SSRF)
7// run BEFORE the fetch — streaming never bypasses them.

1export const POST = nextProxyHandler({
2  baseUrl: "https://api.my-service.com",
3
4  transformRequest: ({ method, endpoint, data }) => ({
5    method,
6    endpoint,
7    data: { ...data, source: "web" },
8  }),
9
10  transformResponse: (res) => ({ ok: true, data: res }),
11
12  maskSensitiveData: (data) => ({ ...data, password: "***" }),
13})

1export const POST = nextProxyHandler({
2  timeoutMs: 30_000, // aborts the upstream fetch; 0 disables. Timeout -> 504
3  log: (event) => {
4    // "request" | "response" | "error" — full detail stays server-side
5    console.log("[proxy]", event)
6  },
7})

1// nextjs-proxy is a ROUTE HANDLER, not middleware — it lives in
2// app/api/proxy/route.ts. You can still gate that route from the
3// framework's edge file if you want a coarse pre-filter.
4
5// Next 13–15:  middleware.ts        | export middleware
6// Next 16:     proxy.ts             | export proxy
7export function proxy(req) {
8  // optional: cheap allowlist / header check before the handler runs
9}
10export const config = { matcher: "/api/proxy" }

1import {
2  proxyFetch,
3  useProxyFetch,
4  ProxyFetchProvider,
5} from "nextjs-proxy"
6
7// All three are re-exported from the same package.
8// No extra dependencies required.

1import { proxyFetch } from "nextjs-proxy"
2
3interface User {
4  id: number
5  name: string
6}
7
8// Basic GET (typed response):
9const res = await proxyFetch<User>({
10  route: "user",
11  data: { id: 42 },
12})
13//  method defaults to "GET"
14//  url defaults to "/api/proxy"
15
16if (res.ok) {
17  console.log(res.data.name) // ✅ typed
18} else {
19  console.log(res.status, res.error)
20}
21
22// POST with data:
23const created = await proxyFetch({
24  route: "users",
25  method: "POST",
26  data: { name: "Alice" },
27  headers: { "X-Request-ID": "abc" },
28})
29
30// The proxyFetch function does NOT throw on HTTP errors.
31// Only network failures (DNS, CORS, timeout) throw.
32// Error classification:
33//   "server" ↦ HTTP 4xx/5xx (returned in response.error)
34//   "network" ↦ fetch threw TypeError (caught with try/catch)
35//   "timeout" ↦ AbortError (caught with try/catch)

1import { useProxyFetch } from "nextjs-proxy"
2
3function UserProfile({ userId }: { userId: number }) {
4  const { data, error, loading, refetch } = useProxyFetch<User>({
5    route: "user",
6    data: { id: userId },
7    enabled: true,        // fetch on mount (default)
8  })
9
10  if (loading) return <div>Loading...</div>
11  if (error)  return <div>{error.message}</div>
12  if (!data)  return <div>No data</div>
13
14  return (
15    <div>
16      <p>{data.name}</p>
17      <button onClick={refetch}>Refresh</button>
18    </div>
19  )
20}
21
22// Polling — auto-refetch every 5 s:
23function LiveNotifications() {
24  const { data: notifications } = useProxyFetch({
25    route: "notifications",
26    refetchInterval: 5_000, // starts after first response
27  })
28  return <ul>{notifications?.map(n => <li key={n.id}>{n.message}</li>)}</ul>
29}
30
31// Callbacks:
32useProxyFetch({
33  route: "orders",
34  onSuccess: (data) => trackEvent("orders_loaded", data),
35  onError:   (err)  => reportError(err),
36})

1import {
2  ProxyFetchProvider,
3  proxyFetch,
4} from "nextjs-proxy"
5
6// Wrap your app (or a subtree):
7<ProxyFetchProvider url="/api/v2/proxy">
8  <App />
9</ProxyFetchProvider>
10
11// Any component inside the provider:
12const res = await proxyFetch({ route: "user" })
13// → uses "/api/v2/proxy"
14
15// Per-call url overrides context:
16const res2 = await proxyFetch({
17  route: "user",
18  url: "/custom-proxy", // forces this URL
19})