Next.js
Build y compilación
Explica qué ejecuta next build: grafos servidor y cliente, bundles por runtime, prerendering, variables, artefactos, caché y errores de producción.
- Última actualización
- Actualizada
- Nivel
- Aplicación
Next.js
Explica qué ejecuta next build: grafos servidor y cliente, bundles por runtime, prerendering, variables, artefactos, caché y errores de producción.
next build no solo transpila TypeScript. Analiza el grafo servidor/cliente, genera bundles por runtime, evalúa rutas, prerenderiza contenido, crea artefactos RSC, optimiza CSS/assets y detecta errores que next dev puede ocultar. El build es una fase de ejecución con acceso a ciertas variables y datos, no una simple conversión de archivos.
source + config + env + lockfile
→ module graph analysis
→ type/build checks
→ client/server/runtime bundles
→ prerender and cache seeds
→ route manifests and assets
→ deployment outputUn import puede ejecutarse durante build aunque pienses que solo se usa por request.
next dev prioriza feedback y recompila bajo demanda. next build:
Por eso “funciona en dev” no confirma producción.
En Next.js 16, Turbopack es el bundler predeterminado para flujos principales. Webpack continúa disponible para compatibilidad mediante configuración/flags documentados.
No mantengas configuración Webpack histórica sin comprobar si todavía es necesaria. Plugins/loaders personalizados pueden impedir migración y aumentar build time.
"use client" crea una entrada al grafo cliente. Todo import transitivo debe ser compatible y puede aumentar bundle.
server-only detecta import accidental desde cliente. El build también valida serialización y conventions.
Durante build, Next.js puede ejecutar Server Components y funciones cacheadas:
build environment
→ query CMS/API
→ produce HTML/RSC/cache entrySi el servicio no está disponible, el build falla. Decide:
No uses production DB durante preview sin aislamiento.
NEXT_PUBLIC_* at build
→ inlined into client bundle
private env used by prerender
→ required during build
private runtime env
→ injected when server startsPromover el mismo artefacto conserva valores públicos de origen. Valida env por capacidad para no exigir secretos innecesarios en todos los builds.
Build verifica TypeScript bajo configuración Next, pero no debes depender de él como único typecheck si tu pipeline necesita tsc --noEmit explícito.
En versiones actuales, lint se ejecuta por separado. Pipeline:
lint
→ typecheck
→ tests
→ next buildNo uses ignoreBuildErrors como solución permanente. Convierte una advertencia en riesgo de producción.
.next contiene:
No lo edites manualmente. Una limpieza puede resolver un artefacto local corrupto, pero no sustituye diagnóstico.
Fija:
Instala con modo frozen/ci. Un build que resuelve versiones distintas no es reproducible.
CI puede cachear package store y .next/cache, no el output final como si fuera universal. La key debe considerar:
Una cache vieja puede producir resultados incoherentes.
El build debe conocer paquetes transpilados y outputs. Declara dependencias y env en Turborepo/Nx para invalidación correcta.
No dependas de archivos fuera del tracing sin configurarlos; standalone puede omitirlos.
Next.js necesita paths/imports analizables:
import(`./locales/${locale}.json`)puede generar un contexto amplio o fallar según caso. Usa mapas explícitos.
Rutas dinámicas y generateStaticParams deben tener límites para evitar builds enormes.
Causas:
Mide por fase. No deshabilites prerender global si el problema es una consulta N+1 de build.
Un build puede quedarse sin heap por grafo, páginas o generación. Opciones:
Puede habilitarse según versión/configuración. Añade tiempo de compilación y exige código compatible; no sustituye profiling ni corrige arquitectura. Actívalo gradualmente y compara bundle/renders/build.
Paquete browser-only ejecutado en servidor/import time.
Valor requerido durante prerender/build.
Ruta intenta leer request context donde el modelo espera prerender/cache/Suspense.
Diferencia de mayúsculas.
OS/arquitectura/Node distintos.
Dependencia de build no disponible.
No entregues secretos de producción a builds de PR no confiables. Usa datos fake/preview y permisos mínimos.
Los scripts de dependencias se ejecutan durante install; revisa supply chain y lockfile.
portfolio build
→ fetch published Sanity data
→ generate public routes and metadata
→ build client chunks
→ emit standalone/server outputSi Sanity falla, decide si build debe detenerse o usar snapshot; no publiques silenciosamente contenido vacío.
use client determina bundle.ignoreBuildErrors?NEXT_PUBLIC_* del build original.Output y self-hosting toma los artefactos y define cómo operarlos.