Mejores Prácticas de Patrones de Next.js

Un resumen condensado de las 25 mejores prácticas más importantes extraídas de cada página en esta sección.

Combina Middleware y Layout Auth: Usa middleware de borde para una comprobación rápida de "¿hay una cookie de sesión?" y realiza la verificación real de JWT/base de datos en un Server Component o layout — el middleware no puede consultar una base de datos, así que omitir el segundo paso deja pasar cookies falsificadas.
Protege Secretos con server-only: Pon import "server-only" en la parte superior de cualquier módulo que toque AUTH_SECRET, URLs de base de datos o claves de firma para que un Client Component que lo importe falle la compilación en lugar de filtrar el valor al paquete del navegador.
Refuerza las Cookies de Sesión: Establece httpOnly: true para bloquear el acceso de JS, secure: true en producción para requerir HTTPS, y sameSite: "lax" para protección básica de CSRF; sameSite: "none" además requiere secure: true o el navegador descarta la cookie completamente.
Usa NextRequest, No Request: Importa NextRequest/NextResponse de next/server para obtener .nextUrl, .cookies, .geo, y ayudantes estáticos como NextResponse.json() sin tener que reconstruirlos sobre la Request Web.
Espera Parámetros Dinámicos en Route Handlers: En Next.js 15+ el segundo argumento es { params: Promise<{ ... }> }; desestructurar sin await params produce una Promise y tu búsqueda retorna silenciosamente undefined.
Envuelve request.json en try/catch: Un cuerpo vacío o malformado hace que await request.json() lance una excepción, así que envu élvelo y retorna { error: "Invalid JSON" } con estado 400 — o valida con un safeParse de Zod para entrada completamente tipada.
Retorna un 204 Simple: Para respuestas sin contenido usa new NextResponse(null, { status: 204 }); NextResponse.json(null, { status: 204 }) envía la cadena "null" como cuerpo y viola el contrato 204.
Usa Actualizaciones Atómicas para Contadores: Para créditos y límites de velocidad, usa updateMany({ where: { credits: { gt: 0 } }, data: { credits: { decrement: 1 } } }) o "incrementa primero, luego verifica, reviertete en desbordamiento" para cerrar la ventana TOCTOU entre lectura y escritura.
Nunca Pongas Secretos Detrás de NEXT_PUBLIC_: Cualquier variable con el prefijo NEXT_PUBLIC_ se inserta en el paquete del cliente en tiempo de compilación, así que reserva esto para claves publicables y URLs públicas — las URLs de base de datos, claves API y secretos de firma deben permanecer solo en servidor.
Evita process.env Dinámico en el Cliente: Next.js hace reemplazo de cadena estática, no búsqueda en tiempo de ejecución, así que process.env[varName] siempre es undefined en código de cliente — solo referencias literales como process.env.NEXT_PUBLIC_APP_URL se insertan.
Valida Env con Zod al Inicio: Analiza process.env a través de un esquema Zod en lib/env.ts para que variables faltantes o malformadas fallen rápidamente con un mensaje claro antes de la primera solicitud, y obtengas un objeto env completamente tipado de forma gratuita.
error.tsx Debe Ser un Client Component: Los Error Boundaries de React dependen del ciclo de vida de clase, así que cada error.tsx necesita "use client" en la parte superior; sin ella la compilación falla y ningún límite se instala para ese segmento.
global-error.tsx Renderiza Su Propio html/body: Cuando el propio layout raíz falla, global-error.tsx reemplaza el documento completo, así que debe renderizar <html><body>…</body></html>; también solo se activa en producción (dev muestra la superposición de Next.js).
Retorna Uniones Discriminadas de Acciones: Tipifica los resultados de Server Action como { success: true; data: T } | { success: false; error: string } para fallos de validación esperados, y reserva throw para errores inesperados que deben activar el error.tsx más cercano.
Llama redirect Fuera de try/catch: redirect() (y notFound()) lanzan un error de centinela NEXT_REDIRECT, así que un try/catch circundante traga la navegación — coloca la llamada después de toda la lógica recuperable o relanza el centinela.
Usa output: standalone y Copia Activos: output: "standalone" produce un servidor autónomo minimalista y autónomo, pero .next/static y public/ no se incluyen — cópialos en el directorio standalone (o frente con un CDN/proxy inverso) o los activos estáticos retornarán 404.
Establece HOSTNAME 0.0.0.0 en Docker: El servidor Next.js se vincula a 127.0.0.1 de forma predeterminada, que es inaccesible desde fuera de un contenedor; establece ENV HOSTNAME="0.0.0.0" (y ENV PORT=3000) en el Dockerfile para que el mapeo de puertos funcione.
Conoce los Límites de Edge Runtime: runtime = "edge" se ejecuta en un aislamiento V8 sin las built-ins de Node — sin fs, path, child_process o Buffer, y debes usar globalThis.crypto; retrocede a "nodejs" siempre que necesites esas APIs.
Establece metadataBase en el Layout Raíz: Todos los URLs relativos en openGraph, twitter y alternates se resuelven contra metadataBase; sin metadataBase: new URL("https://myapp.com") tus imágenes OG y canónicas se envían como rutas relativas rotas.
Usa generateMetadata para Páginas Dinámicas: Para títulos por publicación, descripciones e imágenes OG, exporta async generateMetadata({ params }) (params es una Promise en Next.js 15+) y extiende la antecesor a través del argumento ResolvingMetadata en lugar de duplicar campos.
Usa las Convenciones de sitemap.ts y robots.ts: Exportar una función predeterminada de app/sitemap.ts sirve automáticamente /sitemap.xml y app/robots.ts sirve automáticamente /robots.txt; divide en múltiples Route Handlers de mapa del sitio una vez que un sitio excede el límite de mapa del sitio de 50,000 URLs.
Excluye Activos del i18n Matcher: El middleware de detección de configuración regional debe omitir _next, api y archivos con extensiones (p. ej., matcher: ["/((?!_next|api|favicon.ico).*)"]) o redirige activos estáticos en rutas con prefijo de configuración regional y rompe la página.
Retorna Cada Configuración Regional de generateStaticParams: Prerenderiza todas las configuraciones regionales en tiempo de compilación devolviendo cada una de generateStaticParams; las configuraciones regionales faltantes retornan silenciosamente 404 en producción a menos que dynamicParams esté habilitado.
Simula next/headers y next/cache en Pruebas: cookies(), headers(), revalidatePath y revalidateTag lanzan excepción fuera del contexto de solicitud de Next.js, así que córtalos con vi.mock("next/headers", …) / vi.mock("next/cache", …) antes de importar el módulo bajo prueba.
Espera Server Components Async en Pruebas: Los Server Components son funciones async que retornan JSX, así que en Vitest haz const jsx = await PostList(); render(jsx) en lugar de render(<PostList />); también simula con vi.mock() antes de import() dinámico para asegurar que la simulación gane.

Un resumen condensado de las 25 mejores prácticas más importantes extraídas de cada página en esta sección.

Combina Middleware y Layout Auth: Usa middleware de borde para una comprobación rápida de "¿hay una cookie de sesión?" y realiza la verificación real de JWT/base de datos en un Server Component o layout — el middleware no puede consultar una base de datos, así que omitir el segundo paso deja pasar cookies falsificadas.

Protege Secretos con server-only: Pon import "server-only" en la parte superior de cualquier módulo que toque AUTH_SECRET, URLs de base de datos o claves de firma para que un Client Component que lo importe falle la compilación en lugar de filtrar el valor al paquete del navegador.

Refuerza las Cookies de Sesión: Establece httpOnly: true para bloquear el acceso de JS, secure: true en producción para requerir HTTPS, y sameSite: "lax" para protección básica de CSRF; sameSite: "none" además requiere secure: true o el navegador descarta la cookie completamente.

Usa NextRequest, No Request: Importa NextRequest/NextResponse de next/server para obtener .nextUrl, .cookies, .geo, y ayudantes estáticos como NextResponse.json() sin tener que reconstruirlos sobre la Request Web.

Espera Parámetros Dinámicos en Route Handlers: En Next.js 15+ el segundo argumento es { params: Promise<{ ... }> }; desestructurar sin await params produce una Promise y tu búsqueda retorna silenciosamente undefined.

Envuelve request.json en try/catch: Un cuerpo vacío o malformado hace que await request.json() lance una excepción, así que envu élvelo y retorna { error: "Invalid JSON" } con estado 400 — o valida con un safeParse de Zod para entrada completamente tipada.

Retorna un 204 Simple: Para respuestas sin contenido usa new NextResponse(null, { status: 204 }); NextResponse.json(null, { status: 204 }) envía la cadena "null" como cuerpo y viola el contrato 204.

Usa Actualizaciones Atómicas para Contadores: Para créditos y límites de velocidad, usa updateMany({ where: { credits: { gt: 0 } }, data: { credits: { decrement: 1 } } }) o "incrementa primero, luego verifica, reviertete en desbordamiento" para cerrar la ventana TOCTOU entre lectura y escritura.

Nunca Pongas Secretos Detrás de NEXT_PUBLIC_: Cualquier variable con el prefijo NEXT_PUBLIC_ se inserta en el paquete del cliente en tiempo de compilación, así que reserva esto para claves publicables y URLs públicas — las URLs de base de datos, claves API y secretos de firma deben permanecer solo en servidor.

Evita process.env Dinámico en el Cliente: Next.js hace reemplazo de cadena estática, no búsqueda en tiempo de ejecución, así que process.env[varName] siempre es undefined en código de cliente — solo referencias literales como process.env.NEXT_PUBLIC_APP_URL se insertan.

Valida Env con Zod al Inicio: Analiza process.env a través de un esquema Zod en lib/env.ts para que variables faltantes o malformadas fallen rápidamente con un mensaje claro antes de la primera solicitud, y obtengas un objeto env completamente tipado de forma gratuita.

error.tsx Debe Ser un Client Component: Los Error Boundaries de React dependen del ciclo de vida de clase, así que cada error.tsx necesita "use client" en la parte superior; sin ella la compilación falla y ningún límite se instala para ese segmento.

global-error.tsx Renderiza Su Propio html/body: Cuando el propio layout raíz falla, global-error.tsx reemplaza el documento completo, así que debe renderizar <html><body>…</body></html>; también solo se activa en producción (dev muestra la superposición de Next.js).

Retorna Uniones Discriminadas de Acciones: Tipifica los resultados de Server Action como { success: true; data: T } | { success: false; error: string } para fallos de validación esperados, y reserva throw para errores inesperados que deben activar el error.tsx más cercano.

Llama redirect Fuera de try/catch: redirect() (y notFound()) lanzan un error de centinela NEXT_REDIRECT, así que un try/catch circundante traga la navegación — coloca la llamada después de toda la lógica recuperable o relanza el centinela.

Usa output: standalone y Copia Activos: output: "standalone" produce un servidor autónomo minimalista y autónomo, pero .next/static y public/ no se incluyen — cópialos en el directorio standalone (o frente con un CDN/proxy inverso) o los activos estáticos retornarán 404.

Establece HOSTNAME 0.0.0.0 en Docker: El servidor Next.js se vincula a 127.0.0.1 de forma predeterminada, que es inaccesible desde fuera de un contenedor; establece ENV HOSTNAME="0.0.0.0" (y ENV PORT=3000) en el Dockerfile para que el mapeo de puertos funcione.

Conoce los Límites de Edge Runtime: runtime = "edge" se ejecuta en un aislamiento V8 sin las built-ins de Node — sin fs, path, child_process o Buffer, y debes usar globalThis.crypto; retrocede a "nodejs" siempre que necesites esas APIs.

Establece metadataBase en el Layout Raíz: Todos los URLs relativos en openGraph, twitter y alternates se resuelven contra metadataBase; sin metadataBase: new URL("https://myapp.com") tus imágenes OG y canónicas se envían como rutas relativas rotas.

Usa generateMetadata para Páginas Dinámicas: Para títulos por publicación, descripciones e imágenes OG, exporta async generateMetadata({ params }) (params es una Promise en Next.js 15+) y extiende la antecesor a través del argumento ResolvingMetadata en lugar de duplicar campos.

Usa las Convenciones de sitemap.ts y robots.ts: Exportar una función predeterminada de app/sitemap.ts sirve automáticamente /sitemap.xml y app/robots.ts sirve automáticamente /robots.txt; divide en múltiples Route Handlers de mapa del sitio una vez que un sitio excede el límite de mapa del sitio de 50,000 URLs.

Excluye Activos del i18n Matcher: El middleware de detección de configuración regional debe omitir _next, api y archivos con extensiones (p. ej., matcher: ["/((?!_next|api|favicon.ico).*)"]) o redirige activos estáticos en rutas con prefijo de configuración regional y rompe la página.

Retorna Cada Configuración Regional de generateStaticParams: Prerenderiza todas las configuraciones regionales en tiempo de compilación devolviendo cada una de generateStaticParams; las configuraciones regionales faltantes retornan silenciosamente 404 en producción a menos que dynamicParams esté habilitado.

Simula next/headers y next/cache en Pruebas: cookies(), headers(), revalidatePath y revalidateTag lanzan excepción fuera del contexto de solicitud de Next.js, así que córtalos con vi.mock("next/headers", …) / vi.mock("next/cache", …) antes de importar el módulo bajo prueba.

Espera Server Components Async en Pruebas: Los Server Components son funciones async que retornan JSX, así que en Vitest haz const jsx = await PostList(); render(jsx) en lugar de render(<PostList />); también simula con vi.mock() antes de import() dinámico para asegurar que la simulación gane.

Mejores Prácticas de Patrones de Next.js

Buscar en la documentación

Mejores Prácticas de Patrones de Next.js