Next.js
Explica cómo medir bundles por ruta e interacción, detectar dependencias cliente, duplicación, imports costosos, RSC payload y terceros antes de optimizar.
Optimizar el bundle no significa perseguir el archivo JavaScript más pequeño posible. Significa reducir el código, CSS y terceros que una interacción real debe descargar, parsear y ejecutar. La evidencia proviene del build, el analyzer y las herramientas del navegador, no del número de dependencias en package.json.
source imports
→ dependency graph
→ server/client boundaries
→ chunks per route
→ network transfer
→ parse/compile/execute
→ hydration and interactionUn paquete pesado importado solo por un Server Component puede no llegar al navegador. Un paquete pequeño importado desde root use client puede entrar en todas las rutas.
Una librería de 30 KB que ejecuta un parser costoso puede impactar más que 60 KB de datos simples.
pnpm buildEl modo desarrollo incluye tooling, warnings y Fast Refresh. Analiza producción.
Revisa:
No compares números de builds con configuraciones distintas sin contexto.
Integra una herramienta compatible como @next/bundle-analyzer:
import bundleAnalyzer from "@next/bundle-analyzer";
const withBundleAnalyzer = bundleAnalyzer({
enabled: process.env.ANALYZE === "true",
});
export default withBundleAnalyzer({});ANALYZE=true pnpm buildEl treemap muestra qué módulos forman cada chunk. Pregunta:
Problema:
// app/layout.tsx
"use client";
import HeavyProvider from "heavy-provider";El root layout y sus imports cruzan al grafo cliente. Mejor:
// app/layout.tsx — server
import { Providers } from "./providers";
export default function Layout({ children }: Props) {
return <Providers>{children}</Providers>;
}// providers.tsx — client, but minimal imports
"use client";Aun así, Providers se carga en todas las rutas. Mueve providers de feature a nested layouts.
Funciona mejor con ES modules y exports estáticos:
import { format } from "date-fns";Pero un paquete puede marcar side effects o publicar CommonJS, limitando eliminación.
Evita barrel imports de librerías que reexportan todo cuando el tooling no puede optimizar:
import Button from "library/button";No cambies imports a paths internos no documentados; pueden romper upgrades.
Next.js puede optimizar imports de paquetes con muchos exports bajo configuración soportada:
const nextConfig = {
experimental: {
optimizePackageImports: ["some-library"],
},
};La lista de paquetes optimizados por defecto y el estado de la opción cambian por versión. Mide y consulta docs. No añadas todo node_modules.
Algunas librerías ofrecen plugins o entrypoints específicos. Prefiere API oficial. Un codemod puede migrar imports, pero verifica funcionalidad y tipos.
Dos versiones de React o una librería aumentan bundle y pueden romper Context/Hooks.
pnpm why react
pnpm why zodCausas:
Deduplica sin forzar una versión incompatible.
const Editor = dynamic(() => import("./editor"), {
loading: () => <EditorSkeleton />,
});Aporta cuando la feature es pesada y condicional. No divide un paquete si otro import estático ya lo arrastra al chunk inicial.
El analyzer debe confirmar que realmente se separó.
SDKs admin, ORM y parsers pueden permanecer server-only:
import "server-only";No importes un módulo común que reexporta server y client juntos:
// Avoid barrel mixing boundaries
export * from "./db";
export * from "./button";Separa entrypoints:
feature/server
feature/client
feature/shared“Shared” solo debe contener código ejecutable en ambos entornos:
No debe importar Node APIs, DOM o env privadas.
Un schema Zod grande usado solo en servidor no necesita enviarse al formulario cliente; crea un schema ligero para UX si es necesario y valida completo en servidor.
Importar un paquete completo puede ser costoso según publicación:
import { Trash, Edit } from "icon-library";Muchas librerías modernas tree-shakean; confirma con analyzer. No reemplaces iconos accesibles por SVG copiado sin gestionar aria-hidden, tamaño y mantenimiento.
Moment.js con locales completos es un ejemplo histórico de bundle grande. Intl o una librería modular puede ser suficiente.
Si necesitas locale data, carga únicamente el idioma de la route o mantenlo servidor.
Suelen dominar el bundle. Estrategias:
No reemplaces una librería probada por código propio inseguro solo para ahorrar KB.
Analiza:
Tailwind elimina classes no detectadas, pero safelists amplias vuelven a incluir mucho CSS.
Next.js transpila según targets, pero no toda API runtime recibe polyfill. Un paquete puede traer polyfills globales grandes.
Define navegadores soportados y carga polyfills solo donde se necesiten. No optimices para navegadores fuera del producto sin requisito.
El script inicial puede ser pequeño y cargar mucho después. Usa Performance/Network, no solo analyzer.
Separa:
first-party bundle
+ third-party script
+ requests initiated by third partyElimina proveedores redundantes antes de cambiar estrategias de carga.
Server Components reducen JS, pero pueden enviar props grandes:
<ClientTable rows={thousandsOfRows} />Esto aumenta RSC payload, parseo y memoria. Pasa una ventana/página, mantén render servidor o virtualiza con datos bajo demanda.
No midas solo chunks .js.
Source maps ayudan debugging y pueden subir a un servicio sin publicarse. También aumentan artefactos y pueden revelar source si se exponen.
Configura producción según riesgo y plataforma. No los elimines sin una alternativa de observabilidad.
Antes de reemplazar:
Una alternativa 5 KB menor pero abandonada es un mal trade-off.
Define límites por ruta:
marketing JS initial < target
checkout third-party < target
admin editor loaded on demandIntegra reportes en CI y alerta regresiones. Un límite rígido sin contexto puede bloquear una feature valiosa; requiere owner y excepción documentada.
Portfolio:
Dependencia instalada no implica bundle cliente.
Otro import la mantiene inicial.
Amplía grafo.
Regresión funcional.
Ignora parse/execute.
Datos grandes siguen costando.
Filtra dependencias.
use client.Performance en Next.js amplía el diagnóstico desde bundles hacia red, servidor, React, navegador y experiencia de usuario.