nextjs-proxy

NextJs Proxy

Universal, secure proxy for Next.js. Centralize, audit, and control all external API calls from a single entry point, with support for:

• Security (hides credentials and backend logic)
• Configurable CORS
• Centralized outbound traffic
• Structured auditing and logging
• Request/response transformation
• Access control and validation
• Rate limiting (custom and in-memory included)
• Support for relative endpoints via baseUrl

Ideal for projects with multiple external integrations or governance requirements over outbound traffic.

NextJs Proxy is designed to work seamlessly with the modern, native architecture of Next.js. For optimal performance, security, and maintainability, we recommend combining:

• Rewrites in next.config.js for declarative route mapping
• Middleware for global, centralized logic (auth, rate limiting, logging)
• nextjs-proxy handler for advanced, per-endpoint proxy logic

1. Route Rewrites (next.config.js)

// next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: "/api/proxy/:path*",
        destination: "/api/proxy", // All requests go to your handler
      },
    ];
  },
};

2. Global Middleware (middleware.ts)

Important: If your Next.js project uses the Pages Router (i.e., you have a pages/ folder), the middleware file must be located at src/middleware.ts for Next.js to detect it correctly. If you use only the App Router, it can be in the project root or in src/.

// src/middleware.ts
import { NextResponse, NextRequest } from "next/server";

export function middleware(request: NextRequest) {
  // Example: global authentication
  const token = request.headers.get("authorization");
  if (!token) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }
  // Add logging, rate limiting, etc. here
  return NextResponse.next();
}

// Apply only to proxy routes
export const config = {
  matcher: ["/api/proxy/:path*"],
};

3. Centralized Advanced Logic (Handler)

// app/api/proxy/route.ts
import { nextProxyHandler, nextProxyHandlerAsync } from "nextjs-proxy";

// Versión síncrona (recomendada para la mayoría de casos)
export const POST = nextProxyHandler({
  // ...todas tus opciones avanzadas (logging, transform, masking, etc.)
});

// Versión asíncrona (si necesitas inicialización async)
const handlerPromise = nextProxyHandlerAsync({
  /* opciones */
});
export async function POST(req) {
  const handler = await handlerPromise;
  return handler(req);
}

With this approach you get:

• Native performance and compatibility (serverless/edge)
• Centralized governance and security
• Advanced proxy logic with minimal code duplication
• Easy maintenance and extensibility

This pattern is fully aligned with the best practices recommended by the Next.js team and the evolution of the framework.

⚠️ Warning: (No Turbopack Compatibility) NextJs Proxy is fully compatible with Next.js using Webpack. However, Turbopack (the new experimental bundler for Next.js) currently has limitations with local packages, workspaces, and some advanced module resolution patterns. If you experience issues using this package with Turbopack, consider the following options:

• Recommended: Force the use of Webpack by adding to your next.config.js:

  experimental: {
    turbo: false;
  }
  

• If you want to use Turbopack:
  • Publish the package to npm (even as private) and install it from the registry, not as a local or symlinked package.
  • Avoid cross-dependencies or indirect imports between workspaces.
• Alternative: Bundle your module as a single JS file and consume it as a direct dependency.

Turbopack is under active development and will improve over time. For the latest status, see Vercel Turbopack GitHub.

Installation

pnpm add nextjs-proxy
# or
npm install nextjs-proxy

Quick Usage (App Router)

// app/api/proxy/route.ts
import { nextProxyHandler } from "nextjs-proxy";

export const POST = nextProxyHandler({
  baseUrl: process.env.EXTERNAL_API_BASE,
  allowOrigins: ["http://localhost:3000"],
});

Usage with Pages Router

// pages/api/proxy.ts
import type { NextApiRequest, NextApiResponse } from "next";
import { nextProxyHandler } from "nextjs-proxy";

const handler = nextProxyHandler({ baseUrl: process.env.EXTERNAL_API_BASE });

export default async function proxy(req: NextApiRequest, res: NextApiResponse) {
  // Minimal adapter
  // You may need to create a Request from NextApiRequest if needed
  // App Router is recommended for full compatibility.
  res.status(405).json({ error: "Use App Router for this package" });
}

Combined usage: App Router API + Pages Router frontend

You can use nextjs-proxy in an App Router API route and call it from a Pages Router frontend. This is a common and fully supported scenario in Next.js projects.

API route (App Router):

// src/app/api/proxy/route.ts
import { nextProxyHandler } from "nextjs-proxy";

export const POST = nextProxyHandler({
  baseUrl: "https://your-external-backend.com", // your external backend base URL
  allowOrigins: ["http://localhost:3000"], // adjust as needed
  // You can add more options: log, validate, rateLimit, etc.
});

Advanced Example

export const POST = nextProxyHandler({
  baseUrl: "https://api.my-service.com",
  allowOrigins: ["http://localhost:3000", "https://app.my-domain.com"],
  inMemoryRate: { windowMs: 60_000, max: 100 },
  log: (e) => console.log("[proxy]", e),
  validate: (req) => {
    const auth = req.headers.get("authorization");
    return !!(auth && auth.includes("Bearer "));
  },
  transformRequest: ({ method, endpoint, data }) => ({
    method: method ?? "GET",
    endpoint: endpoint.startsWith("/internal")
      ? endpoint.replace("/internal", "/v2")
      : endpoint,
    data,
  }),
  transformResponse: (res) => ({ ...res, proxiedAt: new Date().toISOString() }),
  maskSensitiveData: (data) => {
    if (!data) return data;
    if (typeof data === "object" && data !== null && "password" in data) {
      return { ...data, password: "***" };
    }
    return data;
  },
});

In a React component (e.g. src/pages/index.tsx), you should use a hook like useEffect to make the request after the component mounts:

import { useEffect } from "react";

export default function Home() {
  useEffect(() => {
    const fetchData = async () => {
      const req = await fetch("/api/proxy", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          method: "GET",
          endpoint: "/v1/health", // relative endpoint, will be resolved with baseUrl
        }),
      });
      const res = await req.json();
    };
    fetchData();
  }, []);

  return (
    <div>
      <h1>Home page</h1>
    </div>
  );
}

This pattern allows you to keep your API logic in the App Router (recommended for new Next.js projects) while using the classic Pages Router for your frontend. Both approaches work together seamlessly.

Full Options

Option	Type	Description
log	(info) => void	Receives events: request, response, error.
validate	(req) => boolean | Promise	Allows to block flow (auth, permissions).
transformRequest	({method,endpoint,data}) => {...}	Modifies payload before fetch.
transformResponse	(res) => any	Adjusts the response before sending to client.
rateLimit	(req) => boolean | Promise	Custom external rate limiting.
inMemoryRate	{ windowMs, max, key? }	Simple in-memory rate limiting.
allowOrigins	string[]	CORS whitelist.
onCorsDenied	(origin) => any	Custom response for denied CORS.
maskSensitiveData	(data) => any	Sanitizes data before sending.
baseUrl	string	Prefix for relative endpoints.

CORS and Preflight

Automatically responds to OPTIONS with headers configured according to allowOrigins.

In-memory Rate Limiting

Minimal configuration:

inMemoryRate: { windowMs: 15_000, max: 20 }

Grouping is by IP (req.ip) or you can define key: (req) => 'user:'+id.

Common Errors

Message	Cause	Solution
Relative endpoint without baseUrl	Used relative endpoint without baseUrl	Define baseUrl in options
Origin not allowed	CORS blocked	Add origin to allowOrigins
Rate limit exceeded	Limit reached	Increase max or window

Comparison: nextjs-proxy vs other Next.js proxy solutions

Next.js offers several ways to proxy API requests. Here’s when to use each approach:

Solution	Use Case	Limitations
Rewrites (next.config.js)	Simple path forwarding, development, no logic needed	Cannot modify headers, no auth, no logging
http-proxy / middleware	Custom API routes, can modify requests, more control	More boilerplate, not native to App Router
next-http-proxy-middleware	Simplifies http-proxy usage in API routes	Still requires custom route, less flexible
@navikt/next-api-proxy	Advanced token exchange, enterprise security	Complex setup, focused on auth scenarios
nextjs-proxy (this package)	Centralized, configurable, minimal, works with App Router	Not for legacy custom servers

Why use nextjs-proxy?

• Native integration with App Router and Pages Router
• Centralized logic: CORS, logging, rate limiting, request/response transformation, access control
• Minimal dependencies, clean API, easy to maintain
• Ideal for projects needing governance, security, and audit over outbound traffic

If you only need simple path forwarding for development, rewrites are enough. For production, security, and advanced logic, use nextjs-proxy.

License

MIT