next-proxy

A simple routing proxy for Next.js.

What is next-proxy?

next-proxy is a library that automatically generates middleware for route protection in Next.js applications. It checks for the presence of an authentication cookie and redirects unauthenticated users from private routes.

Problem it solves

Building route protection in Next.js often requires:

• Writing repetitive middleware logic for each protected route
• Manually managing redirects for unauthenticated users
• Scattering authentication checks across multiple files

next-proxy solves these problems by generating optimized middleware code based on a simple configuration file.

Installation

# npm
npm install @victorcassiano/next-proxy

# yarn
yarn add @victorcassiano/next-proxy

# pnpm
pnpm add @victorcassiano/next-proxy

# bun
bun add @victorcassiano/next-proxy

Quick Start

1. Initialize your project:

npx next-proxy init

2. Configure your routes in proxy.config.ts

3. Build the middleware:

npx next-proxy build

4. Watch for changes during development (optional):

npx next-proxy dev

Configuration

auth (required)

Authentication configuration:

auth: {
  strategy: "cookie",  // Authentication strategy: "cookie" | "header" | "jwt"
  key: "auth_token",   // Cookie name, header name, or placeholder for JWT
}

routes (required)

Define access rules for your routes:

routes: {
  "/": "public",           // Accessible to everyone
  "/login": "public-only", // Only for unauthenticated users
  "/dashboard": "private", // Redirects to unauthenticated URL if no cookie
}

- `"public"` - Accessible to everyone, no authentication required
- `"public-only"` - Only for unauthenticated users. Redirects to `redirects.authenticated` if authenticated
- `"private"` - Redirects to `redirects.unauthenticated` if cookie is not present

Routes support **dynamic segments** and **glob patterns**:
```typescript
routes: {
  "/": "public",
  "/api/:version/users": "private",       // Named param (:param)
  "/users/[id]": "private",               // Next.js bracket param
  "/admin/*": "private",                  // Single-segment wildcard
  "/docs/**": "public",                   // Multi-segment wildcard
}

redirects (required)

Define redirect behavior:

redirects: {
  unauthenticated: "/login",  // Where to redirect unauthenticated users
  authenticated: "/dashboard", // Where to redirect authenticated users (e.g., from /login)
}

fallback (optional)

Default redirect for routes that don't match any configured rule:

fallback: "/",  // Defaults to NextResponse.next() if not specified

output.basePath (optional)

Custom base path for the generated middleware file:

output: {
  basePath: "src/middleware",  // Default: detected from Next.js config
}

Full Example

import { defineNextProxyConfig } from "@victorcassiano/next-proxy";

export default defineNextProxyConfig({
  auth: {
    strategy: "cookie",
    key: "auth_token",
  },
  routes: {
    "/": "public",
    "/login": "public-only",
    "/register": "public",
    "/dashboard": "private",
    "/admin": "private",
    "/profile": "private",
  },
  redirects: {
    unauthenticated: "/login",
    authenticated: "/dashboard",
  },
  fallback: "/",
});

Auth Strategies

Three strategies are supported:

• "cookie" (default) — checks request.cookies.get(key) for a truthy value
• "header" — checks request.headers.get(key) for a truthy value
• "jwt" — validates a JWT from the Authorization: Bearer header using the jose library

// Cookie strategy (default)
auth: { strategy: "cookie", key: "auth_token" }

// Header strategy
auth: { strategy: "header", key: "x-auth-token" }

// JWT strategy (key is required but unused; always reads Authorization header)
auth: { strategy: "jwt", key: "unused" }

next-proxy

Um proxy de roteamento simples para Next.js.

O que é o next-proxy?

next-proxy é uma biblioteca que gera automaticamente middleware para proteção de rotas em aplicações Next.js. Ela verifica a presença de um cookie de autenticação e redireciona usuários não autenticados de rotas privadas.

Problema que resolve

Construir proteção de rotas no Next.js frequentemente requer:

• Escrever lógica de middleware repetitiva para cada rota protegida
• Gerenciar manualmente redirecionamentos para usuários não autenticados
• Espalhar verificações de autenticação por vários arquivos

next-proxy resolve esses problemas gerando código de middleware otimizado baseado em um arquivo de configuração simples.

Instalação

# npm
npm install @victorcassiano/next-proxy

# yarn
yarn add @victorcassiano/next-proxy

# pnpm
pnpm add @victorcassiano/next-proxy

# bun
bun add @victorcassiano/next-proxy

Quick Start

1. Inicialize seu projeto:

npx next-proxy init

2. Configure suas rotas no proxy.config.ts

3. Build o middleware:

npx next-proxy build

4. Watch para alterações durante o desenvolvimento (opcional):

npx next-proxy dev

Configuração

auth (obrigatório)

Configuração de autenticação:

auth: {
  strategy: "cookie",  // Estratégia de autenticação: "cookie" | "header" | "jwt"
  key: "auth_token",   // Nome do cookie, header ou placeholder para JWT
}

routes (obrigatório)

Defina regras de acesso para suas rotas:

routes: {
  "/": "public",           // Acessível para todos
  "/login": "public-only", // Apenas para não autenticados
  "/dashboard": "private", // Redireciona para URL de não autenticado se não houver cookie
}

• "public" - Acessível para todos, sem necessidade de autenticação
• "public-only" - Apenas para não autenticados. Redireciona para redirects.authenticated se autenticado
• "private" - Redireciona para redirects.unauthenticated se o cookie não estiver presente

Rotas suportam segmentos dinâmicos e glob patterns:

routes: {
  "/": "public",
  "/api/:version/users": "private",       // Parâmetro nomeado (:param)
  "/users/[id]": "private",               // Bracket param do Next.js
  "/admin/*": "private",                  // Wildcard de segmento único
  "/docs/**": "public",                   // Wildcard multi-segmento
}

redirects (obrigatório)

Defina o comportamento de redirecionamento:

redirects: {
  unauthenticated: "/login",  // Para onde redirecionar usuários sem cookie de auth
  authenticated: "/dashboard", // Para onde redirecionar usuários autenticados (ex: desde /login)
}

fallback (opcional)

Redirecionamento padrão para rotas que não correspondem a nenhuma regra configurada:

fallback: "/",  // Padrão: NextResponse.next() se não especificado

output.basePath (opcional)

Caminho base personalizado para o arquivo de middleware gerado:

output: {
  basePath: "src/middleware",  // Padrão: detectado a partir da configuração do Next.js
}

Estratégias de Autenticação

Três estratégias são suportadas:

• "cookie" (padrão) — verifica request.cookies.get(key) por um valor truthy
• "header" — verifica request.headers.get(key) por um valor truthy
• "jwt" — valida um JWT do header Authorization: Bearer usando a biblioteca jose

// Estratégia cookie (padrão)
auth: { strategy: "cookie", key: "auth_token" }

// Estratégia header
auth: { strategy: "header", key: "x-auth-token" }

// Estratégia JWT (key é obrigatório mas não usado; sempre lê Authorization header)
auth: { strategy: "jwt", key: "unused" }

Exemplo Completo

import { defineNextProxyConfig } from "@victorcassiano/next-proxy";

export default defineNextProxyConfig({
  auth: {
    strategy: "cookie",     // Também: "header" | "jwt"
    key: "auth_token",
  },
  routes: {
    "/": "public",
    "/login": "public-only",
    "/dashboard": "private",
    "/admin/*": "private",  // Glob: corresponde a /admin/qualquer-coisa
    "/docs/**": "public",   // Globstar: corresponde a /docs/a/b/c
  },
  redirects: {
    unauthenticated: "/login",
    authenticated: "/dashboard",
  },
  fallback: "/",
});