Next.js App Router cambió las reglas de cache, estado y rendering, y muchos equipos llevaron bug de dato viejo a producción antes de entender el nuevo modelo. Las trampas de abajo cuestan días de debug en proyectos reales. Todas pasaron por code review antes del incidente.

¿Por qué mis datos aparecen desactualizados?

El cache es agresivo por default: los requests de fetch entran al Data Cache y los segmentos de ruta quedan guardados hasta que digas lo contrario. Los bugs de stale data rastrean defaults que nadie eligió. force-dynamic, revalidatePath y revalidateTag se vuelven vocabulario diario; aprende cada uno antes del primer deploy, no después del primer ticket.

¿Qué puede cruzar la frontera entre Server y Client Components?

La frontera serializa props: funciones, clases e instancias complejas explotan con error en runtime. La composición con children resuelve la mayoría de los casos; el Server Component arma el árbol y pasa JSX listo hacia abajo. Para lógica ejecutable en el cliente, inyecta hooks propios en vez de intentar cruzar la línea.

¿Por qué mi página carga tan lento?

Un await anidado dentro de Server Components serializa requests en waterfall: el fetch de producto espera el fetch de usuario, que espera la sesión. Promise.all paraleliza lo que no depende entre sí, y los boundaries de Suspense restauran el streaming para lo que puede llegar después. Un waterfall de tres niveles multiplica la latencia de red por tres.

¿Cómo resolver errores de hidratación?

Objetos Date y valores aleatorios divergen entre render del servidor y del cliente y disparan mismatch warnings. Usa serialización determinista: timestamps en ISO string, IDs generados fuera del render, valores formateados con locale fijo. El warning desaparece, y el misterio de producción también.

¿Route Handlers reemplazan a API Routes?

Los handlers del App Router hacen streaming de fábrica, pero el acceso a cookies y headers cambia de forma respecto al Pages Router. El middleware corre antes de todo, incluidos assets estáticos, salvo que el matcher excluya esos caminos. Sin exclusión, cada request de imagen pasa por tu middleware de auth.

¿Sirven las Server Actions para mutations?

Las Server Actions simplifican formularios y aun así exponen endpoints POST; revisa autenticación y autorización dentro de cada action. Redirecciona después de la mutation para impedir doble envío en el refresh. Valida el input con zod como lo harías en una API pública.

¿Por qué mi bundle creció tanto?

Importar una librería server-side en un Client Component infla el bundle hasta que el build falle o la página se ahogue. El paquete server-only fuerza la frontera en tiempo de import y convierte el olvido en error de build. Corre el analyzer de webpack de vez en cuando; el drift del bundle entra sin avisar.

¿Qué cambia en el deploy?

  • Self-hosting exige runtime Node para ISR y optimización de imagen
  • Edge runtime restringe librerías: sin fs, sin drivers nativos de base de datos
  • Recursos específicos de plataforma necesitan adaptadores fuera de Vercel