PassIt

Stop rewriting proxy boilerplate. Never again.

PassIt is a config-driven proxy gateway for Next.js App Router Route Handlers. It sits between your client and your real backend. Handling auth headers, retries, timeouts, error normalization, and logging. So, you don't have to.

Client → Route Handler (PassIt) → Real Backend

Why PassIt?

Every Next.js project that talks to a separate backend ends up writing the same boilerplate:

export async function GET(req: NextRequest) {
  const res = await fetch(`${process.env.BACKEND_URL}/users?${req.nextUrl.searchParams}`, {
    headers: { 'x-api-key': process.env.API_KEY },
  })
  return Response.json(await res.json())
}

Repeated. Every route. Forever.

With PassIt:

export async function GET(req: NextRequest) {
  return passIt({ path: '/users', req })
}

Config lives in one place. Secrets stay server-side. Routes stay clean.

What PassIt Does and Doesn't Do

✅ What PassIt handles

• Proxying client requests to your real backend securely
• Keeping API keys and backend URLs server-side only
• Auto forwarding query params, request body, and dynamic headers
• Merging headers — PassIt headers always win on same key conflict
• Timeout handling with per route override
• Retry logic on configured status codes (onStatus). Also fires on network errors and adapter exceptions.
• Response normalization into consistent success/error shape
• Content-Type detection — handles JSON and plain text responses. HTML responses are consumed and returned as null.
• Logging hooks with dev/prod environment separation
• fetch and axios support via adapter pattern

❌ What PassIt does NOT handle

• Client side data fetching — use axios, SWR, or React Query for that
• CORS — configure that in Next.js or your hosting layer
• Infrastructure concerns — rate limiting, SSL, load balancing belong at the infra level
• Pages Router — Next.js App Router only for now
• Framework agnostic support — Next.js only in v1

🔒 Security model

PassIt runs server side only inside Next.js Route Handlers. Your API keys, backend URLs, and auth tokens never reach the client.

Client (browser)          Your Next.js Server
─────────────────         ──────────────────────────────
knows about:              knows about:
/api/users        →       https://real-backend-api.com/users
                          x-api-key: secret
                          all PassIt logic

Getting Started

Step 1 — Install

npm install @pajarrahmansyah/passit

For axios support (optional):

npm install axios

Step 2 — Create your config

Create passit.config.ts at your project root:

Single service:

import { defineConfig } from '@pajarrahmansyah/passit'

export default defineConfig({
  baseUrl: 'https://api.backend.com',
  headers: {
    'x-api-key': process.env.API_KEY,
  },
})

Multiple services:

import { defineConfig } from '@pajarrahmansyah/passit'

export default defineConfig({
  auth: {
    baseUrl: 'https://auth.backend.com',
    headers: { 'x-api-key': process.env.AUTH_KEY },
  },
  storage: {
    baseUrl: 'https://storage.backend.com',
    headers: { 'x-api-key': process.env.STORAGE_KEY },
  },
})

Step 3 — Load your config

For the most route-safe setup, import the config object in your Route Handler and use the typed passIt function returned by defineConfig. This avoids relying on server startup module order.

// app/api/users/route.ts
import passit from '@/passit.config'
import { NextRequest } from 'next/server'

export async function GET(req: NextRequest) {
  return passit.passIt({ path: '/users', req })
}

If you prefer the package-level passIt import, load your config once during server startup. PassIt stores that registration on globalThis so it can survive separate server module graphs in Next.js App Router.

Choose ONE of these options:

Option 1 — instrumentation.ts (Recommended, Next.js 15+)

Create instrumentation.ts at your project root:

export async function register() {
  await import('./passit.config')
}

Option 2 — instrumentation.ts (Next.js 14)

Add experimental flag to next.config.ts first:

const nextConfig = {
  experimental: {
    instrumentationHook: true,
  },
}
export default nextConfig

Then create instrumentation.ts:

export async function register() {
  await import('./passit.config')
}

Option 3 — Root layout import

Add one line to your app/layout.tsx:

import '@/passit.config'

Option 4 — Next.js plugin + instrumentation

withPassIt enables the instrumentation hook automatically (required for Next.js 14). Pair it with a one-line instrumentation.ts:

// next.config.ts
import { withPassIt } from '@pajarrahmansyah/passit/next'

export default withPassIt({
  // your next.js config
})

// instrumentation.ts
export { register } from '@pajarrahmansyah/passit/next'

Step 4 — Use in your routes

import { passIt } from '@pajarrahmansyah/passit'
import { NextRequest } from 'next/server'

export async function GET(req: NextRequest) {
  return passIt({ path: '/users', req })
}

That's it. PassIt forwards the request, injects your headers, and returns the response. 🔥

Usage Examples

Basic proxy

export async function GET(req: NextRequest) {
  return passIt({ path: '/users', req })
}

With service key (multi service config)

export async function GET(req: NextRequest) {
  return passIt({ service: 'auth', path: '/login', req })
}

With per route overrides

export async function GET(req: NextRequest) {
  return passIt({
    path: '/heavy-report',
    req,
    timeout: false,
    retry: { times: 1, onStatus: [500] },
  })
}

With custom response transformer

export async function GET(req: NextRequest) {
  return passIt({
    path: '/users',
    req,
    response: (data) => ({
      users: data.results,
      total: data.count,
    }),
  })
}

With hooks for logging

export default defineConfig({
  baseUrl: 'https://api.backend.com',
  hooks: {
    dev: {
      onRequest: (req) => console.log(`--> ${req.method} ${req.path}`),
      onResponse: (res) => console.log(`<-- ${res.status} ${res.path} ${res.duration}ms`),
      onError: (err) => console.error(`[error] ${err.message}`),
    },
    prod: {
      onError: (err) => Sentry.captureException(err),
    },
  },
})

Config Reference

defineConfig options

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | baseUrl | string | yes | — | Real backend base URL, no trailing slash | | http | fetch \| axios | no | fetch | HTTP library | | headers | Record<string, string> | no | {} | Static headers injected on every request | | timeout | number \| false | no | 5000 | Timeout in ms, false to disable | | retry | RetryConfig | no | — | Retry on failure | | normalize | boolean \| NormalizeConfig | no | — | Normalize response shape | | hooks | HooksConfig | no | — | Logging and observability |

createPassIt(config) accepts the same config shape and returns a typed passIt function bound to that config without registering it globally.

passIt options

| Option | Type | Required | Description | |--------|------|----------|-------------| | path | string | yes | Backend endpoint path | | req | NextRequest | optional | Next.js request object — see Forwarding vs server-initiated requests | | service | string | optional | Service key for multi service config | | baseUrl | string | no | Overrides global baseUrl | | headers | Record<string, string> | no | Extra headers for this route | | timeout | number \| false | no | Overrides global timeout | | retry | RetryConfig | no | Overrides global retry | | normalize | boolean \| NormalizeConfig | no | Overrides global normalize | | hooks | HooksConfig & { override?: boolean } | no | Route level hooks | | response | (data: unknown) => unknown | no | Custom response transformer. Runs AFTER normalize if both are defined. Disable normalize on that route if you need raw data. |

Note: If both normalize and response are defined, response receives already normalized data. To access raw backend data inside response, set normalize: false on that route.

Forwarding vs server-initiated requests

req is optional and acts as a forwarding switch.

Pass req when the route depends on the incoming client request — query params, request body, or client headers need to reach the upstream:

// Query params, body, and headers from the client are forwarded automatically
export async function GET(req: NextRequest) {
  return passIt({ path: '/users', req })
}

export async function POST(req: NextRequest) {
  return passIt({ path: '/users', req })
}

Omit req when the call is server-initiated and doesn't depend on client input — a health check, a scheduled data fetch, or any route with no dynamic input:

// Server-initiated: no query params, no body, no client headers forwarded
export async function GET() {
  return passIt({ path: '/users' })
}

Warning: If you omit req on a route that actually receives query params or a request body, they will be silently dropped and never reach the upstream. Always pass req when your route handler accepts a NextRequest.

RetryConfig

| Option | Type | Description | |--------|------|-------------| | times | number | Max retry attempts | | onStatus | number[] | Status codes that trigger retry e.g. [500, 502, 503]. Any status code is valid — PassIt does not restrict to 5xx only. Retry also fires on network errors and adapter exceptions. |

NormalizeConfig

| Option | Type | Description | |--------|------|-------------| | success | boolean | Normalize success responses | | error | boolean | Normalize error responses |

Normalized shapes:

// success
{ success: true, status: 200, data: { ...response } }

// error
{ success: false, status: 404, message: 'not found' }

HooksConfig

| Option | Type | Description | |--------|------|-------------| | onRequest | (req: HookRequest) => void | Runs before every request | | onResponse | (res: HookResponse) => void | Runs after every response | | onError | (err: HookError) => void | Runs on every error | | dev | HookHandlers | Runs in development only | | prod | HookHandlers | Runs in production only |

Requirements

• Next.js >= 14.0.0
• Node.js >= 18.0.0
• axios >= 1.0.0 (optional)

Roadmap

• v1 — Next.js App Router, full feature set
• v2 — Staging environment hooks, Pages Router support
• v3 — Framework agnostic

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

License

MIT © Pajar Rahmansyah