Mejores prácticas de configuración de Next.js

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

1. Genera un AUTH_SECRET Real: Auth.js requiere una AUTH_SECRET de 32+ caracteres; usa npx auth secret para obtener un valor criptográficamente fuerte, y da secrets diferentes para dev y prod para que una key dev filtrada no comprometa sesiones reales.
2. Separa auth.config de auth.ts: Mantén un auth.config.ts (edge-safe) (sin adaptadores, sin drivers de BD) separado de auth.ts donde conectas el adaptador de base de datos, para que middleware pueda llamar a auth() bajo el Edge Runtime sin arrastrar código Node-only.
3. Aumenta el tipo Session: Declara claims personalizadas en Session y JWT en types/next-auth.d.ts vía module augmentation para que session.user.role, subscriptionStatus, etc. estén tipadas en cada Server Component, action y middleware.
4. Fija create-next-app para Reproducibilidad: Los defaults de CLI varían entre versiones y el modo interactivo silenciosamente reutiliza preferencias cacheadas, así que fija create-next-app@15 (o la major que quieras) y pasa --reset-preferences o flags explícitos en CI para que los scaffolds sean determinísticos.
5. Cachea fetch Explícitamente en Next 15: El default en Next.js 15+ es cache: "auto", no force-cache, así que establece cache o next: { revalidate: N } en cada fetch en lugar de asumir que los datos están cacheados — el fetching silencioso por-solicitud es una regresión común respecto a Next 14.
6. Copia static y public a standalone: output: "standalone" produce un servidor diminuto autónomo pero excluye .next/static y public/ — tu Dockerfile o script de despliegue debe copiar ambos, sino la app sirve 404s para assets.
7. Establece HOSTNAME=0.0.0.0 en Contenedores: El servidor standalone se vincula a 127.0.0.1 por default, así que dentro de un contenedor Fargate/EKS/Docker debes establecer ENV HOSTNAME=0.0.0.0 (y un PORT explícito) o el health check del load balancer nunca alcanza la app.
8. Usa un Cache Handler ISR Compartido: Los datos ISR se cachean por-contenedor por default, así que despliegues multi-contenedor muestran versiones inconsistentes hasta que configures un cacheHandler respaldado por Redis en next.config con cacheMaxMemorySize: 0.
9. Prefiere pm2 reload Sobre restart: En EC2, pm2 reload hace un graceful rolling restart en cluster workers para despliegues zero-downtime; pm2 restart mata todos los workers y produce una ventana de outage visible.
10. Deja que Nginx Sirva _next/static: Configura Nginx para servir /_next/static/ y public/ directamente con Cache-Control: public, immutable, max-age=31536000 para que los assets estáticos eviten Node completamente y sobrevivan reinicios de app.
11. Preserva .next/cache Entre Despliegues: Los scripts de despliegue deben eliminar .next/server/ y .next/static/ pero guardar .next/cache/ para que los cachés ISR y de compilación sobrevivan; un blunt rm -rf .next los borra y fuerza reconstrucciones completas más regeneración ISR fría.
12. Usa un Cliente Prisma Singleton: Adjunta el cliente a globalThis en development para que hot-reload no abra un nuevo connection pool en cada guardado — sin esto, Postgres rechaza nuevas conexiones en minutos y el dev server se cuelga.
13. Pon DATABASE_URL en .env: El Prisma CLI lee .env, no .env.local, así que prisma generate y migrate fallan silenciosamente o con mensajes confusos si la URL solo vive en .env.local.
14. revalidatePath Después de Mutaciones: Server Actions que escriben datos deben llamar a revalidatePath (o revalidateTag) después, sino el render cacheado de Server Component sigue sirviendo datos obsoletos y la UI parece no actualizar.
15. Usa prisma migrate deploy en CI: Los pipelines de CI deben ejecutar prisma migrate deploy (no-interactivo, aplica migraciones confirmadas); prisma migrate dev es interactivo, puede resetear la base de datos, y nunca debe ejecutarse contra production o staging.
16. Valida Frontmatter MDX Con Zod: gray-matter devuelve las keys que happen estar en el archivo, así que ejecuta el resultado a través de un schema Zod para atrapar typos y campos requeridos faltantes en tiempo de importación en lugar de hacer ship de docs rotas.
17. Escapa Braces y JSX en MDX Prose: Las llaves curvas se evalúan como JavaScript y <Tag /> se parsea como JSX, así que envuelve ejemplos de código en backticks o escapa las braces — sino MDX lanza build errors en prose que se ve bien en plain Markdown.
18. Crea Clientes Stripe en Signup: Crea el cliente Stripe en Auth.js events.createUser, no durante checkout, para que no haya double-click race que produzca clientes duplicados y el usuario tenga un Stripe ID en el momento que existan.
19. Verifica Webhooks Stripe Con constructEvent: Un webhook handler de Stripe debe leer el cuerpo raw y llamar a stripe.webhooks.constructEvent(rawBody, sig, whsec); parsear JSON sin verificar la signature deja que cualquiera mute tu base de datos vía POSTs forjados.
20. Fuerza nodejs Runtime para Webhooks: Establece export const runtime = "nodejs" en la ruta webhook de Stripe porque crypto.createHmac no está disponible en el Edge Runtime, y usa un STRIPE_WEBHOOK_SECRET distinto por entorno o las signatures fallan silenciosamente.
21. Tailwind v4 Config Vive en CSS: Tailwind v4 no tiene tailwind.config.js — los tokens de tema, variantes y plugins se declaran en globals.css vía @theme y @custom-variant, y el plugin PostCSS es @tailwindcss/postcss, no el viejo paquete tailwindcss.
22. Siempre Compone Classes Con cn(): Los componentes shadcn colapsan utilidades en conflicto vía cn() (clsx + tailwind-merge), así que concatena classes a través de cn(...) en lugar de template strings — sino los overrides de prop de consumer aleatoriamente pierden contra defaults.
23. Declara env Vars en turbo.json: Turborepo despoja cualquier variable de entorno no listada en el array env de la tarea, así que vars no-listadas son undefined en build time; declara cada env var de build time explícitamente o cache keys no reflejarán tu configuration.
24. transpilePackages para Workspace UI: Next.js no compilará TSX raw desde node_modules, así que cuando consumes paquetes monorepo internos como @repo/ui añádelos a transpilePackages en next.config.ts o imports erroan en build.
25. Usa workspace: Con pnpm:* El protocolo workspace:* solo lo entienden pnpm, yarn, y bun — npm no lo parsea; establece "packageManager": "pnpm@…" en root package.json y usa --frozen-lockfile en CI para evitar drift.