Next.js 16+ y Turbopack — Guía de Referencia

⚡

Turbopack vs Webpack

	Turbopack	Webpack
Dev por defecto	Sí (Next 16+)	No (legacy)
Cold start	5–14× más rápido	Lento en proyectos grandes
HMR latencia	<300ms	1–5s
Cache en disco	Nativo (.next)	Config manual
Plugins webpack	No soporta	Ecosistema completo
Production build	Verificar versión	Estable (legacy)
Middleware	proxy.ts (Next 16)	middleware.ts

📊

Benchmarks — Cultiva SaaS

Proyecto: 200 rutas, App Router, 80 server components

Cold start (ms)

Turbopack

3.2s

Webpack

44.8s

HMR (hot reload)

Turbopack

180ms

Webpack

2.8s

Reinicio (con cache)

Turbopack

0.9s

Webpack

22s

💻

Comandos esenciales

# Desarrollo local (Turbopack por defecto en Next.js 16)

$next dev

# Forzar webpack si hay bug o plugin incompatible

$next dev --webpack

# Build de producción

$next build

# Bundle Analyzer (Next.js 16.1+)

$ANALYZE=true next build

# Limpiar cache Turbopack si hay problemas

$rm -rf .next/cache

# Verificar versión de Next.js

$next --version

🔍

Diagnóstico — Dev lento

⚠️

Cache corrompida o inexistente

Si cold start es >10s incluso en reinicios, el cache no está funcionando.

→ rm -rf .next/cache && next dev

⚠️

Webpack activo en lugar de Turbopack

Puede pasar si hay una flag --webpack en package.json scripts.

→ Revisar "dev" script en package.json, quitar --webpack

✅

App Router + Server Components

Turbopack optimiza especialmente server components. App Router correcto.

→ Mantener estructura app/ y maximizar 'use server'

ℹ️

node_modules pesados en client bundle

chart.js y framer-motion aumentan el tiempo de compilación inicial.

→ Usar Bundle Analyzer y aplicar dynamic import()

📦

Bundle Analyzer — Top dependencias

Análisis de cultiva-saas / client bundle · gzip

chart.js 148 kB

lazy

framer-motion 94 kB

split

@sentry/nextjs 62 kB

keep

date-fns 31 kB

split

react-table 18 kB

keep

Ahorro potencial con lazy loading:

−242 kB del bundle inicial

✅

Buenas prácticas

1

Mantén Next.js 16.x actualizado
Turbopack recibe fixes de estabilidad y mejoras de cache en cada release menor.

2

No borres .next/cache sin motivo
El cache incremental es la ventaja clave. Solo bórralo si sospechas corrupción.

3

Usa proxy.ts para middleware en Next 16
El nombre cambió de middleware.ts a proxy.ts. No renombres; romperías el middleware.

4

Maximiza Server Components
Turbopack optimiza mejor server components. Usa 'use client' solo cuando sea estrictamente necesario.

5

Analiza bundles en cada sprint
ANALYZE=true next build para detectar dependencias pesadas antes de que crezcan.

6

Fallback a webpack solo con causa
Si un plugin requiere webpack, documenta por qué y crea un issue en el plugin para soporte Turbopack.

⛔ No renombres proxy.ts a middleware.ts

En proyectos Next.js 16+, proxy.ts es el nombre correcto del archivo de middleware. Renombrarlo a middleware.ts romperá la ejecución del middleware silenciosamente.