sideEffects en package.json: la promesa que poda módulos enteros

El tree shaking que has visto hasta aquí poda exports no usados, pero se topa con un muro: ¿y si un módulo, además de exportar cosas, hace cosas con solo importarlo? Un import './estilos.css', un polyfill que parchea un prototipo, una llamada que registra un componente global. Ante esa posibilidad, el bundler es prudente por obligación: conserva el módulo aunque no uses ninguno de sus exports, porque eliminarlo podría borrar un efecto que alguien esperaba. El campo sideEffects en package.json es cómo un paquete rompe ese empate declarando, bajo su responsabilidad, que importar sus módulos no tiene efectos observables —y así autoriza al bundler a podarlos enteros.

El problema: exports sin usar pero efectos presentes

El análisis de alcance responde a “¿se usa este export?”, pero esa no es la pregunta completa. Un módulo puede no exportar nada que tú toques y aun así importar ese módulo puede cambiar el estado del mundo: escribir en window, extender Array.prototype, inyectar una hoja de estilos, registrarse en un contenedor de dependencias. Esos son sus efectos secundarios, y ocurren por el mero hecho de que el módulo se evalúe.

Por eso el bundler no puede limitarse a mirar los exports. Si elimina un módulo cuyos exports nadie usa, pero ese módulo tenía un efecto, rompe el programa de una forma silenciosa y difícil de rastrear. Ante la duda, la respuesta correcta es conservadora: mantener el módulo evaluándose por si su sola ejecución importaba. Esa prudencia es sensata, pero también es la que impide podar módulos perfectamente prescindibles.

El dilema del bundler es real y no tiene salida por análisis puro: mirando el código de un módulo, no siempre puede decidir si evaluarlo tiene o no efectos observables. Un efecto puede esconderse tras una llamada opaca, tras un getter, o tras una rama que solo se toma en cierto entorno. Frente a esa incertidumbre, la única política correcta es la pesimista —conservar—, y de ahí que módulos perfectamente inertes acaben en el bundle solo porque el bundler no puede probar que lo son.

// registro.js — no exporta nada util para ti, pero AL IMPORTARSE actua
window.__miApp = window.__miApp || {}
window.__miApp.plugins = []

// polyfill.js — parchea un prototipo con solo evaluarse
if (!Array.prototype.at) {
  Array.prototype.at = function (i) { /* ... */ }
}

Los efectos que fuerzan a conservar un módulo forman un catálogo reconocible, y saber identificarlos es la mitad del trabajo, porque son justo los que el campo sideEffects gobierna:

• Inyectar estilos: un import './x.css' que no exporta nada pero adjunta una hoja al documento.
• Parchear el entorno: un polyfill que añade un método a un prototipo o a un objeto global.
• Registrarse en algún sitio: apuntar un componente, un plugin o un handler en un registro compartido.
• Escribir estado global: inicializar una variable en window, en globalThis o en un singleton.
• Emitir un efecto observable al importar: telemetría, un log, o abrir una conexión de red.

Todos comparten un rasgo: ocurren al evaluar el módulo, no al llamar a lo que exporta. Esa es exactamente la clase de comportamiento que el bundler no puede descartar por su cuenta, porque eliminarlo cambiaría el comportamiento del programa de una forma que ningún análisis de exports llega a ver.

sideEffects: false, la promesa de pureza

El campo sideEffects de package.json es la forma de un paquete de decirle al bundler: “puedes fiarte, importar cualquiera de mis módulos no provoca efectos observables”. Con esa promesa, el bundler se libera de su prudencia: si ninguno de los exports de un módulo se usa, puede eliminar el módulo entero, no solo los bindings sueltos.

{
  "name": "mi-libreria",
  "sideEffects": false
}

La diferencia práctica es enorme y se ve mejor con el caso canónico: los barriles. Muchas librerías exponen un index.js que reexporta decenas de módulos —export * from './debounce', export * from './throttle', y así cien veces—. Si importas solo debounce, sin sideEffects: false el bundler teme que evaluar los otros noventa y nueve módulos tuviera efectos, así que los conserva. Con sideEffects: false, sabe que puede descartar los noventa y nueve módulos que no alcanzas y quedarse únicamente con el de debounce.

El efecto sobre el tamaño se mide en órdenes de magnitud, no en porcentajes. Una utilidad monolítica sin sideEffects puede colarte cientos de kilobytes por el simple hecho de importar una función, porque su barril conecta con todo y el bundler no se atreve a soltar nada; la misma utilidad con el campo bien puesto entrega esa función y prácticamente nada más. Por eso, cuando evalúas una dependencia por su peso, comprobar si declara sideEffects te dice más que contar sus líneas de código.

La lista de globs: cuando algunos archivos sí tienen efectos

Pocos paquetes son totalmente puros. Lo habitual es que casi todo sea podable salvo un puñado de archivos con efectos legítimos: los estilos, un polyfill, un punto de registro. Para eso sideEffects acepta, en vez de un booleano, una lista de patrones que enumera los archivos que sí tienen efectos y deben conservarse siempre.

{
  "sideEffects": [
    "*.css",
    "./src/polyfills.js"
  ]
}

La forma de la lista es un glob por entrada, con la sintaxis habitual de comodines, interpretado contra las rutas de los archivos del paquete. Es deliberadamente escueta: no describe qué efecto tiene cada archivo, solo que lo tiene y, por tanto, que no debe podarse aunque sus exports queden sin usar. Toda la expresividad que necesita es distinguir dos conjuntos, el de lo conservable y el de lo podable.

La semántica es una lista blanca invertida: todo lo que no coincide con esos patrones se considera puro y podable; lo que coincide se preserva aunque nadie use sus exports. El caso más frecuente es "*.css", porque un import './boton.css' no exporta nada pero su efecto —inyectar estilos— es justo lo que quieres. Sin ese patrón, un sideEffects: false demasiado entusiasta eliminaría tus estilos por considerarlos un import sin exports usados.

Conviene entender la lista como un mecanismo de grano fino que preserva la máxima poda. En vez de renunciar al tree shaking de todo el paquete porque tres archivos tienen efectos, aíslas esos tres y dejas que el resto se sacuda con libertad. Es la diferencia entre apagar la optimización por una excepción y acotar la excepción para salvar la optimización.

flowchart TD
A[modulo con exports sin usar] --> B{el paquete declara sideEffects}
B -->|no declara nada| C[se conserva por prudencia]
B -->|false| D[se elimina el modulo entero]
B -->|lista de globs| E{coincide con un patron}
E -->|si| F[se conserva]
E -->|no| D
style D fill:#a6e3a1,color:#11111b
style C fill:#f9e2af,color:#11111b
style F fill:#89b4fa,color:#11111b

El peligro de declarar mal

Como toda promesa que una herramienta se cree, sideEffects es tan peligrosa como útil. Si declaras sideEffects: false en un paquete que sí tiene un efecto —un polyfill, un registro global, un CSS importado por su efecto— el bundler te tomará la palabra y podará ese módulo cuando nadie use sus exports. El resultado es un bug de los peores: no falla el build, no falla en dev, y solo en producción, cuando el árbol se sacude de verdad, desaparece el efecto y algo deja de funcionar sin un error claro que lo explique.

Lo que vuelve a este fallo tan escurridizo es su distancia respecto a la causa, en el tiempo y en el espacio. Quien declaró mal el sideEffects pudo ser el autor de una dependencia, meses atrás; quien sufre el síntoma eres tú, en producción, viendo cómo un estilo no se aplica o un método no existe, sin nada que apunte al package.json responsable. Los efectos podados no dejan huella en el error: simplemente, algo que debía suceder al importar no sucedió, y hay que deducirlo por ausencia.

La regla es tratar el campo con el rigor de una firma. Marca false solo si estás seguro de que ningún módulo depende de su evaluación; en cuanto haya efectos, enuméralos con la lista de globs en vez de mentir con un booleano. Y recuerda que consumes esta promesa constantemente: cuando tú importas una dependencia y no se poda como esperabas, muchas veces es porque a ella le falta declarar bien su sideEffects.

Hay una asimetría cruel entre los dos modos de equivocarse, y entenderla fija el sesgo correcto. Si eres demasiado tímido —no declaras sideEffects teniéndolo todo puro— el castigo es un bundle algo más grande: molesto, pero visible y sin consecuencias funcionales. Si eres demasiado audaz —declaras pureza donde hay efectos— el castigo es un bug de producción sin rastro. La timidez cuesta bytes; la audacia cuesta corrección. Ante la duda, el sesgo prudente es nítido: no prometas una pureza que no puedas defender archivo por archivo.