Por qué el tree shaking depende de los módulos ES y no funciona con CommonJS

Eliminar el código que no se usa parece un problema de análisis y es en realidad un problema de demostración: el empaquetador solo puede borrar algo si puede probar que borrarlo no cambia el comportamiento del programa. Con módulos ES esa prueba es posible en muchos casos porque la forma del módulo es conocida antes de ejecutar nada. Con CommonJS la prueba es imposible en el caso general, y no por falta de esfuerzo de las herramientas, sino por la semántica del formato.

Enlaces estáticos frente a un objeto que se rellena

La diferencia de raíz es que en un módulo ES las importaciones y exportaciones son declaraciones, no expresiones. Están en el nivel superior, no pueden estar dentro de un if, no pueden construirse con una cadena calculada, y el motor las resuelve antes de ejecutar una sola línea del módulo.

// modulo.js — la forma del modulo es conocida sin ejecutarlo
export function alfa() { return 1; }
export function beta() { return 2; }
export const GAMMA = 3;

// consumidor.js
import { alfa } from './modulo.js';
console.log(alfa());

El empaquetador, sin ejecutar nada, sabe tres cosas: que modulo.js exporta exactamente alfa, beta y GAMMA; que consumidor.js usa exclusivamente alfa; y que nadie más importa ese módulo. Con eso puede demostrar que beta y GAMMA no son alcanzables, y borrarlas es una transformación que preserva el comportamiento.

Ahora el equivalente en CommonJS:

// modulo.cjs
exports.alfa = function () { return 1; };
exports.beta = function () { return 2; };
exports.GAMMA = 3;

// consumidor.cjs
const m = require('./modulo.cjs');
console.log(m.alfa());

Aquí exports es un objeto normal de JavaScript, y require es una función que se ejecuta. Para saber qué exporta el módulo hay que ejecutarlo. Y como es un objeto normal, cualquier cosa puede pasar:

// Todo esto es CommonJS valido, y ninguna herramienta puede analizarlo estaticamente
if (process.env.MODO === 'completo') {
  exports.extra = require('./extra.cjs');
}
for (const nombre of Object.keys(tabla)) {
  exports[nombre] = crearManejador(nombre);
}
module.exports = new Proxy({}, { get: (_, k) => generar(k) });

Un empaquetador que quisiera recortar tendría que resolver, en tiempo de compilación, qué vale process.env.MODO, qué claves tiene tabla y qué devuelve un proxy arbitrario. Eso es equivalente al problema de la parada. No es que las herramientas no lo hagan bien: es que no se puede hacer.

De ahí la regla operativa: ante un módulo CommonJS, el empaquetador conservador lo incluye entero. Es la única transformación que garantiza no romper nada.

Qué sí puede probar el análisis estático

Merece la pena precisar qué demuestra realmente el análisis, porque también se sobreestima.

Puede probar que una exportación no se importa desde ningún sitio. Es el caso base y el que más rinde.

Puede probar que una rama es inalcanzable con constantes conocidas. Si process.env.NODE_ENV se sustituye por la cadena "production" en tiempo de compilación, el bloque del if de desarrollo se convierte en código muerto y desaparece. Esto es lo que hace que el mismo código pese distinto en desarrollo y en producción.

Puede probar que una función pura cuyo resultado no se usa se puede borrar. «Pura» significa sin efectos secundarios observables, y ahí está el problema: el empaquetador no puede demostrar la pureza en el caso general. Lo que hace es asumir que ciertas construcciones son puras —una declaración de función, una expresión de clase, un literal de objeto— y ser conservador con todo lo demás. Por eso existen las anotaciones explícitas de pureza:

// El comentario le dice al empaquetador: si nadie usa 'config', borra la llamada
export const config = /* @__PURE__ */ construirConfiguracion();

Sin ese comentario, una llamada a función en el nivel superior se conserva siempre, porque podría estar registrando algo, modificando un global o lanzando una excepción.

Lo que no puede probar nunca es lo que ocurre a través de una indirección dinámica. Acceso a propiedad con clave calculada, eval, proxies, Function construida desde una cadena. Cualquiera de esas cosas obliga a conservar.

Cómo saber si una dependencia se está incluyendo entera

Tres señales, de más rápida a más fiable.

El campo del package.json de la dependencia. Si no hay module ni un exports con condición import, el paquete solo publica CommonJS:

npm view la-biblioteca --json | grep -E '"main"|"module"|"exports"|"type"'

Un paquete con "main": "dist/index.js" y nada más, sin "type": "module", es CommonJS puro.

El peso en el informe del bundle. Si importas una función de una biblioteca y el informe muestra la biblioteca completa, no se ha recortado.

La prueba directa. Compila con la importación y sin ella, y compara. Es lo único que no admite discusión, y es el tema de verificar que se eliminó.

Qué hacer con una dependencia solo en CommonJS

Cuatro salidas, en orden de preferencia.

Buscar el paquete con módulos ES equivalente. Muchas bibliotecas populares publican una variante o han añadido el punto de entrada moderno en versiones recientes. Actualizar la versión mayor es a menudo todo lo que hace falta.

Importar el submódulo concreto. Aunque el paquete sea CommonJS, si su estructura de ficheros permite importar directamente el fichero que necesitas, te llevas solo ese fichero y sus dependencias:

// Arrastra el paquete entero
const { throttle } = require('la-biblioteca');

// Arrastra solo un fichero y lo que el importe
const throttle = require('la-biblioteca/throttle');

Funciona si el paquete no restringe las rutas internas con el campo exports. Si lo hace, esta salida se cierra.

Cargarla de forma diferida. Si no se puede recortar, al menos que no esté en el arranque. Un import() la saca de la ruta crítica y el problema del tamaño se convierte en un problema de latencia, que es mucho más manejable.

Sustituirla. La última salida, con el coste que ya conoces del árbol de decisión de dependencias.

node -e "
  const m=JSON.parse(require('fs').readFileSync('meta.json','utf8'));
  const cuenta={};
  for(const k of Object.keys(m.inputs)){
    const mm=k.match(/node_modules\/((?:@[^/]+\/)?[^/]+)/);
    if(!mm) continue;
    (cuenta[mm[1]] ??= new Set()).add(k.includes('/esm/')||k.endsWith('.mjs')?'esm':'cjs');
  }
  for(const [p,f] of Object.entries(cuenta)) if(f.size>1) console.log('DOBLE FORMATO:', p);
"

// vite.config.js
export default {
  resolve: {
    alias: { 'la-biblioteca': 'la-biblioteca/dist/index.mjs' },
    dedupe: ['la-biblioteca', 'react', 'react-dom'],
  },
};

El resumen operativo

Tres frases que resumen el nivel entero desde el punto de vista de las dependencias.

Publica y consume módulos ES. Si mantienes una biblioteca, publica con el campo exports y condición import, y declara sideEffects. Es lo que permite a tus usuarios recortarla.

Comprueba el formato antes de instalar. Dos comandos, cinco minutos, y evitas una dependencia que no se puede recortar nunca.

No confíes en que el recorte ha funcionado. Compruébalo. La cantidad de configuraciones en las que el tree shaking está teóricamente activado y prácticamente desactivado es enorme, y la única forma de saberlo es medir el bundle.