Next.js en producción

Úsalo para cualquier código en una aplicación Next.js 16 App Router. Las reglas específicas de seguridad (autenticación en acciones, CSP, cabeceras, taint) están en nextjs-security; las reglas de contenedor en docker-nextjs. La skill integrada de Claude Code next-best-practices cubre las convenciones generales de archivos, metadatos, optimización de imágenes y fuentes en profundidad; esta skill solo agrega lo específico de cómo construimos y publicamos.

Línea base: Next 16.4, React 19.3, Turbopack (predeterminado para dev y build), cacheComponents: true con partialPrefetching: true, output: "standalone", typedRoutes: true. El next.config.ts de la plantilla es la fuente de verdad.

Reglas

Componentes servidor por defecto; "use client" solo para estado, efectos, APIs del navegador o manejadores de eventos. Pon la directiva en la hoja más pequeña que la necesite. No la agregues porque un archivo importa nuvui: las partes con estado de nuvui llevan su propia directiva (consulta la skill nuvui, rules/server-components.md).
```
// Mal: toda la página es cliente por un solo manejador
"use client";
export default function Page() { … <Select onValueChange={…} /> … }

// Bien: la página permanece en el servidor, el manejador vive en una hoja
export default async function Page() {
  const people = await getPeople();
  return <PeopleFilter people={people} />; // people-filter.tsx tiene "use client"
}
```
Las props que cruzan a un componente cliente deben ser serializables: sin funciones (excepto Server Actions), sin instancias de clase.
Obtén datos en el servidor, en el componente que necesita los datos. Sin useEffect para obtener datos, sin manejador de ruta solo para alimentar tu propia página. Desduplica por solicitud con cache() de React; almacena en caché entre solicitudes con la regla 3.
Almacena en caché con "use cache" + cacheLife + cacheTag; todo lo demás es dinámico. Con Componentes de Caché, nada se almacena en caché a menos que lo indiques, y fetch no tiene caché implícita.
```
import { cacheLife, cacheTag } from "next/cache";

export async function getInvoice(id: InvoiceId) {
  "use cache";
  cacheLife("minutes");
  cacheTag(`invoice:${id}`);
  return db.invoice.findUnique({ where: { id } });
}
```
No uses la configuración de segmento antigua (export const dynamic, revalidate, fetchCache): da error bajo Componentes de Caché. Los argumentos y valores cerrados pasan a formar parte de la clave de caché, así que pasa ids, no objetos de solicitud completos. Detalles, los perfiles y "use cache: private": references/caching.md.
Invalida con updateTag en Server Actions, revalidateTag(tag, "max") en otros lugares. updateTag(tag) proporciona consistencia de lectura-después-de-escritura y solo funciona dentro de una Server Action. Desde un webhook o manejador de ruta usa revalidateTag(tag, "max") (stale-while-revalidate) o revalidateTag(tag, { expire: 0 }). La versión de un solo argumento revalidateTag(tag) está obsoleta.
Envuelve los datos en tiempo de solicitud en <Suspense>, o la compilación falla. cookies(), headers(), searchParams, connection() y E/S no almacenada en caché fuera de un límite de Suspense detienen el prerenderizado con "datos no almacenados en caché o en tiempo de ejecución durante el prerenderizado". Asígnale un límite con un fallback esqueleto, almacena en caché, o (solo en el layout raíz, ver regla 14) marca la ruta como bloqueante con export const instant = false. Todos params, searchParams, cookies(), headers() son asíncronos: haz await de ellos.

Cada Server Action valida su entrada y verifica la autorización por sí misma. Una Server Action es un endpoint POST público sin importar en qué página esté escrita. Analiza FormData con el esquema de typescript-production (valibot), luego autoriza, luego muta, luego updateTag. Devuelve un resultado tipado para fallos esperados; lanza solo para errores. El conjunto completo de reglas está en nextjs-security.

"use server";
export async function renameProject(_: State, form: FormData): Promise<State> {
  const session = await requireSession();                  // 401 si está ausente
  const input = v.safeParse(RenameProject, Object.fromEntries(form));
  if (!input.success) return { ok: false, errors: flatten(input.issues) };
  await assertCanEdit(session, input.output.projectId);    // 403 si no está permitido
  await db.project.update(…);
  updateTag(`project:${input.output.projectId}`);
  return { ok: true };
}

Los manejadores de ruta son para otros clientes (webhooks, móvil, salud), no para tus propias páginas. Ponlos bajo app/api/. Valida el cuerpo como una acción, devuelve Response.json(...), y establece códigos de estado intencionadamente.
Cada aplicación tiene GET /api/health, dinámico y sin dependencias. El HEALTHCHECK de Docker y los probes de Kubernetes lo golpean. Debe responder sin tocar la base de datos, para que una dependencia lenta no reinicie cada pod. await connection() evita que se prerenderice en un archivo estático. Está en la plantilla en src/app/api/health/route.ts; proxy.ts excluye /api/health de su matcher.
error.tsx, loading.tsx y not-found.tsx en la raíz, y por segmento donde la UX difiere. error.tsx es un componente cliente; registra a través de onRequestError de instrumentation.ts, muestra un reintento con reset, nunca el mensaje de error. Llama a notFound() para registros faltantes en lugar de renderizar un estado vacío.
NEXT_PUBLIC_* se hornea en la compilación; todo lo demás se lee en tiempo de ejecución en el servidor. Una imagen se promociona de main a producción sin cambios, por lo que un valor NEXT_PUBLIC_ es el mismo en todos los entornos. Pon solo constantes de tiempo de compilación allí (nombre de la aplicación, un DSN público de Sentry que es el mismo en todas partes). La configuración por entorno (URLs de API, feature flags, secretos) es un process.env.X del lado del servidor, leído en un Componente Servidor o acción, y pasado al cliente como props si es necesario. Valida el entorno una vez en src/env.ts (valibot) e importa desde allí. Nunca uses la clave env en next.config.ts: se incluye en los bundles del cliente.
Marca los módulos solo de servidor con import "server-only". Cualquier cosa que lea secretos, hable con la base de datos o importe un SDK con credenciales. Una importación de cliente de ello entonces falla la compilación en lugar de filtrar.
after() para trabajo que no debería retrasar la respuesta (registros de auditoría, analíticas, calentamiento de caché). Lee cookies()/headers() antes de llamar a after, no dentro de él. Se ejecuta en el mismo proceso, por lo que el pod necesita su período de gracia SIGTERM (el chart establece terminationGracePeriodSeconds).
Instrumenta con src/instrumentation.ts: registerOTel + onRequestError. OpenTelemetry a través de @vercel/otel, exportador configurado por las variables de entorno estándar OTEL_EXPORTER_OTLP_* en tiempo de ejecución. Consulta references/observability.md.
Mantén output: "standalone" y nunca importes desde fuera del workspace. El runner de Docker copia solo .next/standalone, .next/static y public. En el monorepo, server.js aterriza en .next/standalone/apps/<app>/server.js; la raíz del workspace se encuentra desde pnpm-lock.yaml, así que no establezcas outputFileTracingRoot o turbopack.root a menos que la compilación advierta. Detalles de autoalojamiento (múltiples réplicas, claves de Server Action, deploymentId): references/self-hosting.md.
El layout raíz lee el nonce CSP, por lo que la aplicación se renderiza por solicitud. El proxy.ts de la plantilla establece un CSP basado en nonce y src/app/layout.tsx tiene export const instant = false. Eso es un intercambio deliberado: los nonces y los shells estáticos prerenderizados no pueden coexistir, y para aplicaciones empresariales con inicio de sesión, un CSP estricto gana. El almacenamiento en caché de datos con "use cache" aún funciona. No elimines ninguna de las dos mitades sin leer la regla 4 de nextjs-security.
Estilos: SCSS BEM global, importado por el componente. Turbopack compila Sass con el paquete sass; sassOptions.loadPaths: ["src/styles"] hace que @use "abstracts" funcione desde cualquier profundidad. Sin imports ~, sin sassOptions.functions. Reglas en scss-bem.
Imágenes a través de next/image, fuentes a través de next/font. sharp viene con Next para el optimizador; la imagen del runner no necesita paquete adicional. Las imágenes remotas necesitan images.remotePatterns con un nombre de host exacto.
Verifica el tamaño del bundle con pnpm next analyze (el analizador de Turbopack; @next/bundle-analyzer es solo para webpack). Carga bajo demanda los widgets pesados del cliente (editor nuvui, mapas, gráficos debajo del pliegue) con next/dynamic.
Usa rutas tipadas y tipos generados. typedRoutes: true verifica <Link href>; PageProps<"/invoices/[id]"> y LayoutProps son globales después de next typegen (se ejecuta automáticamente con next dev/next build). No escribas manualmente los tipos params.
Sin next lint. Fue eliminado en la versión 16. Biome lint (consulta biome); TypeScript verifica con tsc --noEmit por paquete.

Verificar

pnpm typecheck
pnpm lint
pnpm build                      # turbo run build: falla en errores de prerender, errores de tipo, errores de Sass
pnpm --filter <app> start &     # luego:
curl -fsS localhost:3000/api/health

Nuvraxis/nuvraxis-plugins

¿Qué es nuvraxis-plugins?

Preguntar en tu IA favorita

Documentación

Next.js en producción

Reglas

Verificar

Fuentes

Individual skills in this repo