Traductor de Markdown

Hemos estado observando que Turbopack madurara desde su anuncio allá en 2022, ejecutándolo en modo de desarrollo desde Next.js 14, y observando cautelosamente esas banderas "turbo" en CI. Cuando Next.js 16 llegó a principios de 2025 con Turbopack como el bundler de producción predeterminado, sabíamos que la migración no podía esperar más. Teníamos tres proyectos de clientes en Next.js 15 que necesitaban actualización, y voy a guiarte a través de cada cambio significativo, los problemas que encontramos, y los números de rendimiento que vimos en el otro lado.

Esto no es un resumen de las notas de la versión. Esto es lo que realmente sucedió cuando ejecutamos next build con Turbopack en bases de código reales con complejidad real.

Tabla de Contenidos

Compilaciones de Producción de Next.js 16 Turbopack: Qué Cambió y Cómo Migramos

Por qué Next.js 16 es Importante

Next.js 16 no es solo un cambio de versión. Representa el cambio más significativo en la infraestructura de compilación desde que el framework pasó de Pages a App Router. La característica principal es obvia: Turbopack reemplaza webpack como el bundler predeterminado para compilaciones de desarrollo y producción.

Pero hay más sucediendo. Next.js 16 también incluye:

  • React 19 como versión mínima soportada — sin más compatibilidad con React 18
  • Mejora en la madurez de streaming y prerendering parcial
  • Nuevos valores predeterminados de caché que son realmente sensatos (aprendieron del rechazo de caché de Next.js 15)
  • APIs de solicitud asincrónica completamente aplicadas — cookies(), headers() y params son todos asincrónicos ahora sin soporte sincrónico heredado
  • Requisito mínimo de Node.js 20 — el soporte para Node 18 se ha eliminado

Para agencias como la nuestra que hacen desarrollo con Next.js, este es el tipo de versión que toca todo. No puedes simplemente cambiar el número de versión y dejarlo así.

Qué Cambió Realmente con Turbopack en Producción

Seamos específicos. Durante Next.js 14 y 15, Turbopack estaba disponible para next dev con la bandera --turbo. Las compilaciones de producción seguían usando webpack. Next.js 15.3 introdujo una bandera experimental --turbopack para next build, y cuando se lanzó la versión 16, se convirtió en la predeterminada.

Aquí está lo que es fundamentalmente diferente en cómo Turbopack maneja compilaciones de producción en comparación con webpack:

Arquitectura de Compilación Incremental

Webpack procesa todo tu gráfico de dependencias en cada compilación. Turbopack usa un sistema de caché a nivel de función basado en el motor Turbo (escrito en Rust). En la práctica, esto significa que las compilaciones posteriores solo recompilan lo que realmente cambió. Tu primera compilación podría no ser dramáticamente más rápida, pero tu segunda, tercera y décima compilación lo serán.

Mejoras en Tree Shaking

El tree shaking de Turbopack opera a un nivel más granular que el de webpack. Notamos que nuestros paquetes de cliente eran 8-15% más pequeños en promedio en nuestros tres proyectos sin ningún cambio de código. Las mayores ganancias vinieron del manejo de archivos barrel — Turbopack es genuinamente mejor eliminando re-exportaciones no utilizadas de archivos de índice.

Resolución de Módulos

Turbopack resuelve módulos de manera diferente. Es más rápido, pero también es más estricto. Si tenías rutas de importación descuidadas que webpack estaba resolviendo silenciosamente (como extensiones de archivo faltantes en ciertos casos límite, o rutas insensibles a mayúsculas en macOS que se rompen en Linux), Turbopack las detectará. Esto causó aproximadamente el 30% de nuestros problemas de migración.

Estrategia de División de Código

El algoritmo de división de chunks es nuevo. Turbopack crea más chunks más pequeños de forma predeterminada. Esto generalmente mejora el rendimiento de carga para navegadores modernos con HTTP/2, pero puede aumentar el número total de solicitudes. Vimos que el número de chunks aumentaba aproximadamente un 40% mientras que el tamaño total del bundle disminuía.

SWC es Ahora Obligatorio

Si todavía estabas aferrándote a cualquier configuración de Babel, se ha ido. Turbopack usa exclusivamente SWC para la transformación. Esta ya era la dirección en que las cosas se dirigían, pero Next.js 16 elimina cualquier alternativa a Babel completamente.

Benchmarks de Rendimiento de Compilación

Aquí hay números reales de nuestros tres proyectos de migración. Estos no son benchmarks sintéticos — son de aplicaciones de clientes reales ejecutándose en nuestro pipeline de CI en GitHub Actions (Ubuntu, ejecutores de 4 vCPU, 16GB RAM).

Métrica Proyecto A (E-commerce) Proyecto B (Dashboard SaaS) Proyecto C (Sitio de Contenido)
Páginas/Rutas 847 124 2,340
compilación webpack (Next 15) 4m 32s 1m 48s 6m 15s
compilación Turbopack (Next 16, en frío) 3m 10s 1m 22s 4m 44s
compilación Turbopack (Next 16, caché cálido) 1m 05s 28s 1m 52s
cambio en tamaño de bundle -12% -8% -14%
Carga Inicial de JS (página de inicio) -18KB -7KB -22KB
pico de memoria de compilación 3.8GB → 2.9GB 1.6GB → 1.2GB 4.2GB → 3.1GB

Los números de caché cálido son la verdadera historia. Una vez que Turbopack ha compilado tu proyecto una vez, las compilaciones incrementales posteriores son dramáticamente más rápidas. Para nuestro Proyecto C de contenido pesado (que usa un CMS sin cabeza con miles de páginas generadas estáticamente), pasar de 6+ minutos a menos de 2 minutos en compilaciones cacheadas fue significativo. Ese es dinero real ahorrado en minutos de CI.

Las mejoras en el uso de memoria también fueron significativas. El Proyecto A ocasionalmente golpeaba errores de falta de memoria en ejecutores de CI más pequeños con webpack. Ese problema desapareció con Turbopack.

Compilaciones de Producción de Next.js 16 Turbopack: Qué Cambió y Cómo Migramos - arquitectura

Cambios Disruptivos que Necesitas Conocer

Aquí hay una lista actualizada de todo lo que realmente se rompió durante nuestras migraciones. La guía de actualización de Next.js 16 cubre algunos de estos, pero algunos nos sorprendieron.

1. Configuración Personalizada de Webpack

Este es el grande. Si tienes una clave webpack en tu next.config.js, ya no funciona. Turbopack tiene su propia API de configuración bajo turbopack en la configuración de Next.js. No todo tiene una asignación 1 a 1.

// next.config.js — ANTES (Next.js 15 con webpack)
module.exports = {
  webpack: (config) => {
    config.module.rules.push({
      test: /\.svg$/,
      use: ['@svgr/webpack'],
    });
    return config;
  },
};

// next.config.js — DESPUÉS (Next.js 16 con Turbopack)
module.exports = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
};

2. APIs de Solicitud Sincrónica Removidas

Next.js 15 deprecó el acceso sincrónico a cookies(), headers(), params y searchParams. Next.js 16 las elimina completamente. Si ignoraste esas advertencias de deprecación, vas a pasar un mal rato.

// ANTES — esto se rompe en Next.js 16
export default function Page({ params }) {
  const { slug } = params;
  return <div>{slug}</div>;
}

// DESPUÉS
export default async function Page({ params }) {
  const { slug } = await params;
  return <div>{slug}</div>;
}

Esto parece trivial pero tocó más de 200 componentes en nuestros proyectos. Escribimos un codemod para manejar la mayoría (más sobre eso a continuación).

3. React 18 Ya No es Soportado

Next.js 16 requiere React 19. Si tienes dependencias fijadas en React 18, necesitan actualización. La mayoría de las librerías bien mantenidas tenían soporte para React 19 a mediados de 2025, pero encontramos un par de rezagados.

4. Node.js 18 Descontinuado

El mínimo es Node.js 20. Actualiza tus imágenes Docker, configuraciones de CI y archivos .nvmrc.

5. Cambios en next/image

La propiedad onLoadingComplete está completamente removida (fue deprecada desde Next.js 14). Usa onLoad en su lugar. El pipeline de optimización de imágenes también usa una nueva librería subyacente, lo que significa que tus imágenes optimizadas cacheadas se regenerarán en la primera solicitud.

Nuestro Proceso de Migración Paso a Paso

Aquí está el proceso actual que seguimos. Hicimos el Proyecto B (el más pequeño) primero como prueba, luego abordamos A y C.

Paso 1: Auditar Dependencias

Antes de tocar Next.js, auditamos cada dependencia para verificar compatibilidad con React 19 y Node.js 20. Usamos un script simple:

npx npm-check-updates --target latest --filter '/react|next/'

También revisamos manualmente nuestros paquetes más críticos: nuestro SDK de CMS sin cabeza, librería de autenticación y librería de componentes UI.

Paso 2: Actualizar Node.js

Actualizamos nuestro .nvmrc a 20.18.0 (último LTS en ese momento), actualizamos Dockerfiles y verificamos ejecutores de CI. Simple pero fácil de olvidar.

Paso 3: Actualizar React Primero

npm install react@19 react-dom@19 @types/react@19 @types/react-dom@19

Ejecutamos la suite de prueba completa aquí antes de proceder. React 19 tiene sus propios cambios disruptivos (removió la necesidad de forwardRef, ref es ahora una propiedad regular, el hook use() es estable). Arreglamos esos problemas de forma aislada para no estar debuggeando problemas de React y Next.js simultáneamente.

Paso 4: Ejecutar el Codemod de Next.js

Next.js proporciona un codemod de actualización que maneja muchos de los cambios mecánicos:

npx @next/codemod@latest upgrade

Esto manejó aproximadamente el 70% de las migraciones de API asincrónica automáticamente. No es perfecto — tuvo dificultades con algunos de nuestros patrones de componentes de servidor más complejos — pero nos ahorró horas.

Paso 5: Actualizar Next.js

npm install next@16

Paso 6: Migrar next.config.js

Este fue el paso más intensivo en tiempo para el Proyecto A, que tenía una significativa personalización de webpack. Cubriré las traducciones específicas en la siguiente sección.

Paso 7: Arreglar Errores de Compilación Iterativamente

Ejecutamos next build y solucionamos errores uno por uno. Los mensajes de error de Turbopack son realmente mejores que los de webpack en la mayoría de casos — más específicos, con rutas de archivo más claras y sugerencias.

Paso 8: Prueba de Regresión Visual

Usamos Playwright para pruebas E2E y ejecutamos nuestra suite de regresión visual para detectar cualquier diferencia de renderizado. Encontramos dos problemas: una diferencia en el orden de CSS (Turbopack procesa importaciones de CSS en un orden ligeramente diferente que webpack) y una importación dinámica que no estaba dividiendo código correctamente.

Paso 9: Validación de Rendimiento

Comparamos puntuaciones de Lighthouse y Core Web Vitals antes y después. Cada proyecto mejoró o se mantuvo neutral. Sin regresiones.

Traducciones de Configuración de Webpack

Esta sección es para equipos con configuraciones personalizadas de webpack. Aquí hay cómo se traducen los patrones comunes a Turbopack.

Cargadores Personalizados

// Equivalente de Turbopack para cargadores personalizados
module.exports = {
  turbopack: {
    rules: {
      '*.md': {
        loaders: ['raw-loader'],
        as: '*.js',
      },
      '*.graphql': {
        loaders: ['graphql-tag/loader'],
        as: '*.js',
      },
    },
  },
};

Alias de Módulos

// Los alias de resolución funcionan similarmente
module.exports = {
  turbopack: {
    resolveAlias: {
      'old-package': 'new-package',
      // También puedes apuntar a archivos locales
      '@legacy/utils': './src/utils/legacy.ts',
    },
  },
};

Qué No Se Traduce

Algunos plugins de webpack simplemente no tienen equivalentes de Turbopack aún:

  • webpack.DefinePlugin — Usa env en next.config.js o variables de entorno directamente
  • BundleAnalyzerPlugin — El paquete @next/bundle-analyzer funciona con Turbopack a partir de v16, pero el formato de salida cambió
  • División de chunks personalizada vía splitChunks — Turbopack maneja esto automáticamente y no expone el mismo nivel de control. Honestamente, los valores predeterminados son suficientes para la mayoría de proyectos.
  • webpack.IgnorePlugin — Usa resolveAlias para apuntar importaciones a módulos vacíos

Manejo de Paquetes de Terceros

Algunos paquetes causaron problemas durante la migración:

@sentry/nextjs — Necesitaba v9+ para compatibilidad con Turbopack. Las versiones anteriores se conectaban a internos de webpack. La actualización fue directa pero requirió cambios de configuración.

next-intl — Funcionó bien después de actualizar a la última versión. El API del plugin se adaptó limpiamente.

@vanilla-extract/next-plugin — Este fue nuestro mayor dolor de cabeza en el Proyecto B. El plugin de webpack de Vanilla Extract no tenía un equivalente de Turbopack hasta su lanzamiento v2.0. Tuvimos que esperar por eso o considerar alternativas. Esperamos.

Paquetes de archivos barrel — Cualquier paquete que exporte cientos de componentes desde un archivo de índice único (mirándote a ti, librerías de iconos) ahora se hace tree-shake mucho más agresivamente. Esto es una buena cosa, pero vimos un caso donde un icono referenciado dinámicamente no se estaba incluyendo. Pasamos de búsquedas de iconos basadas en cadena a importaciones directas, que es mejor práctica de todas formas.

Consideraciones de CSS y Tailwind

Si estás usando Tailwind CSS (y la mayoría de nuestros proyectos lo hacen), la migración es principalmente indolora. Tailwind v4 funciona excelente con Turbopack. Pero hay algunas cosas a observar:

Orden de Importación de CSS

Turbopack procesa importaciones de CSS en un orden determinista pero diferente que webpack. Si estás confiando en el orden de importación para la especificidad (y no deberías, pero seamos honestos — todos terminamos ahí a veces), podrías ver diferencias visuales. Tuvimos un proyecto donde un reset global estaba siendo anulado por un CSS module de componente porque el orden de importación se invirtió.

La solución fue el uso explícito de @layer en nuestro CSS, que debería haber estado haciendo todo el tiempo.

CSS Modules

Los CSS Modules funcionan de forma idéntica. Sin cambios necesarios. Los nombres de clase generados se ven diferentes (más cortos, realmente), pero eso es cosmético a menos que estés haciendo algo raro como dirigir nombres de clase generados en pruebas.

PostCSS

Los archivos de configuración de PostCSS se siguen respetando. Tu postcss.config.js continúa funcionando. Sin cambios necesarios aquí.

Actualizaciones de Implementación y Pipeline de CI

Nuestros objetivos de implementación son principalmente Vercel y AWS (vía SST/OpenNext). Aquí hay lo que cambió:

Vercel: Detectó automáticamente Next.js 16 y usó Turbopack. La integración del caché de compilación funciona de forma inmediata. Nuestros tiempos de compilación en Vercel cayeron aún más dramáticamente que en CI local porque Vercel tiene integración profunda con la capa de caché de Turbopack. El Proyecto C fue de ~8 minutos a ~2.5 minutos en Vercel.

AWS/OpenNext: Requirió actualización a OpenNext 4.x, que agregó soporte de salida de Turbopack. El formato de salida cambió ligeramente — la estructura de directorio .next se reorganizó — así que cualquier script posterior a la compilación que hiciera referencia a rutas de archivo específicas necesitaba actualización.

compilaciones Docker: Si estás compilando Next.js en Docker, actualiza tu imagen base a Node 20+ y ten en cuenta que el directorio de caché de Turbopack (.next/cache/turbopack) debe incluirse en tu estrategia de caché de capas de Docker. Agregamos una capa específica de COPY para esto.

# Optimizar caché de capas Docker para Turbopack
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
# Montaje de caché para Turbopack
RUN --mount=type=cache,target=/app/.next/cache \
    npm run build

Cuándo No Deberías Migrar Aún

No quiero pintar esto como todo color de rosa. Hay razones legítimas para permanecer en Next.js 15 por ahora:

  • Dependencia pesada de plugins de webpack: Si tu compilación se basa en 3+ plugins de webpack personalizados que no tienen equivalentes de Turbopack, el costo de migración podría no valer la pena aún.
  • Monorepo con configuración compartida de webpack: Si estás compartiendo configuración de webpack en un monorepo entre proyectos de Next.js y no-Next.js, dividir esa configuración es trabajo adicional.
  • Requisitos de estabilidad: Next.js 16.0 es estable, pero 16.1 y 16.2 arreglaron bugs reales. Esperaría al menos 16.2+ antes de migrar cualquier cosa en la que no puedas tolerar tiempo de inactividad.
  • Dependencias heredadas atrapadas en React 18: Si una dependencia crítica no ha agregado soporte para React 19, estás bloqueado de todas formas.

Para equipos que hacen desarrollo de CMS sin cabeza, la migración es generalmente más suave porque los sitios impulsados por CMS tienden a tener configuraciones de compilación más simples.

Preguntas Frecuentes

¿Es Turbopack lo suficientemente estable para producción en Next.js 16? Sí. Turbopack ha estado en desarrollo durante más de tres años, fue probado en modo de desarrollo en millones de proyectos de Next.js, y pasó por una beta extendida en compilaciones de producción durante Next.js 15.3-15.5. Lo hemos estado ejecutando en producción desde el lanzamiento de la versión 16.0 en múltiples sitios de clientes sin problemas relacionados con bundlers. Dicho esto, si estás en 16.0 específicamente, actualiza a 16.2+ donde se resolvieron varios bugs de casos límite.

¿Puedo seguir usando webpack con Next.js 16? No como el bundler principal, no. Turbopack es el único bundler soportado en Next.js 16. Si absolutamente necesitas webpack, tendrás que permanecer en Next.js 15, que recibirá parches de seguridad hasta principios de 2026. Vercel ha sido clara que el soporte de webpack en Next.js ha terminado.

¿Cuánto más rápido es Turbopack comparado con webpack para compilaciones de producción? En compilaciones en frío (sin caché), vimos mejoras de 20-30%. En compilaciones cálidas/cacheadas, la mejora salta a 50-70%. Los números exactos dependen fuertemente del tamaño del proyecto, número de rutas y la cantidad de generación estática sucediendo. El uso de memoria también cayó 20-30% consistentemente en nuestros proyectos.

¿Necesito reescribir mi next.config.js para Turbopack? Si tienes configuración personalizada de webpack en tu next.config.js, sí — esos bloques necesitan ser traducidos al formato de configuración de turbopack. Si solo estás usando opciones estándar de configuración de Next.js (imágenes, redirecciones, reescrituras, variables de entorno), todas funcionan exactamente igual. El esfuerzo de migración es proporcional a cuánta configuración personalizada de webpack tengas.

¿Funcionará mi pipeline de CI/CD existente con Next.js 16? Mayormente sí. Las principales cosas a actualizar son: versión de Node.js (mínimo 20), cualquier script que haga referencia a archivos de salida específicos de webpack, y cualquier estrategia de caché que apunte a .next/cache/webpack. Querrás cachear .next/cache/turbopack en su lugar. Si estás implementando en Vercel, todo se maneja automáticamente.

¿Turbopack soporta todas las mismas características que webpack en Next.js? Para características específicas de Next.js, sí — App Router, Pages Router, rutas API, middleware, ISR, SSG, SSR todo funciona. Para configuración personalizada de webpack, hay aproximadamente 90% de paridad de características. Los gaps restantes son principalmente alrededor de plugins de webpack de nicho y estrategias de división de chunks altamente personalizadas. Consulta los documentos de compatibilidad de Turbopack para tu caso de uso específico.

¿Debería migrar a Next.js 16 o considerar alternativas como Astro? Depende de tu caso de uso. Si estás construyendo aplicaciones altamente interactivas con gestión de estado compleja, Next.js 16 es una opción fuerte y las mejoras de Turbopack hacen la DX significativamente mejor. Si estás construyendo sitios de contenido pesado con interactividad mínima, Astro sigue siendo una excelente alternativa con su modelo de hidratación parcial. Hemos estado construyendo con ambos y eligiendo basado en requisitos del proyecto. Si no estás seguro, contáctanos y podemos ayudarte a evaluar.

¿Cuál es el tiempo mínimo necesario para migrar una aplicación de Next.js 15 de tamaño medio a 16? Para una aplicación típica de tamaño medio (50-200 rutas, dependencias estándar, configuración mínima personalizada de webpack), presupuesta 2-4 días de tiempo de desarrollador. Eso incluye actualizaciones de dependencias, migraciones de API asincrónica, pruebas y verificación de implementación. Si tienes configuración extensiva personalizada de webpack o dependencias heredadas, podría tomar una semana o más. Nuestro equipo en Social Animal ofrece servicios de migración si prefieres no quemar el sprint de tu equipo en trabajo de infraestructura.