Externals: no empaquetes lo que el consumidor ya tiene

Una app incrusta sus dependencias dentro del bundle porque es el último eslabón: nadie más va a resolverlas, así que las mete todas y cierra el paquete. Una librería debe hacer exactamente lo contrario. Cada dependencia que empaquetas dentro de tu dist es código que viajará duplicado en el árbol del consumidor, que romperá el estado compartido de las librerías que exigen una sola copia, y que le negará a quien te instala la posibilidad de podar y versionar lo que ya tenía. La regla que gobierna esta lección es tajante: tu paquete publicado contiene tu código y solo tu código. Todo lo demás son aristas que salen de tu grafo y que cierra el consumidor, no tú.

Externalizar: dejar las aristas abiertas

Cuando el bundler recorre tu grafo y encuentra un import a react, tiene dos opciones: seguir esa arista, entrar en el código de React y copiarlo dentro de tu salida, o detenerse en el borde y dejar el import tal cual, apuntando a un react que alguien resolverá después. Marcar una dependencia como external es elegir la segunda: le dices al bundler que no cruce esa arista, que la deje abierta, que confíe en que el consumidor tiene su propia copia de react y sabrá conectarla.

// rollup.config.js — externalizar es cerrar el grafo en el borde
export default {
  input: "src/index.ts",
  external: ["react", "react-dom", "lodash-es"],
  output: { file: "dist/index.js", format: "es" },
};

El resultado es un dist que preserva sus import a las dependencias en vez de incrustarlas. Tu código sale intacto; sus referencias a lo ajeno quedan como especificadores desnudos que el bundler del consumidor resolverá contra su node_modules. Esa es la forma correcta de un paquete de librería: un artefacto que contiene tu lógica y una lista de puentes hacia lo que espera encontrar montado del otro lado.

En la práctica no enumeras cada paquete a mano. El convenio es externalizar todo lo que figure en dependencies y peerDependencies del package.json, porque justamente eso es lo que el consumidor va a instalar. Las herramientas modernas de empaquetado de librerías lo hacen por defecto: leen tu manifiesto y tratan como external cuanto declaras depender, de modo que solo acaba en el bundle tu propio código y, como mucho, lo que tengas en devDependencies y uses de verdad en runtime.

dependencies frente a peerDependencies

No todas las dependencias que dejas fuera son iguales, y la diferencia entre dependencies y peerDependencies es una de las más malentendidas del empaquetado. Una dependency normal es tuya: tu librería la necesita, tú eliges su versión, y el gestor de paquetes instalará la copia que a ti te va bien, aunque el consumidor no sepa que existe. Es la relación por defecto para utilidades internas que no tienen que ser compartidas con nadie.

Una peerDependency es una declaración distinta: dice que tu librería necesita un paquete que el consumidor ya tiene y debe compartir contigo. El caso canónico es un plugin de React: tu librería usa React, pero no quiere su propia copia —quiere exactamente la misma instancia que usa la app, porque React guarda estado interno (los hooks, el contexto) que se rompe si conviven dos copias. Con peerDependencies le dices al consumidor: “no te instalo React, te exijo que tú tengas uno compatible y lo compartas conmigo”.

{
  "name": "mi-plugin-react",
  "peerDependencies": {
    "react": ">=18"
  },
  "devDependencies": {
    "react": "^19"
  }
}

Fíjate en el doble juego: react aparece en peerDependencies —lo exiges al consumidor con un rango amplio— y en devDependencies —lo instalas solo para compilar y testear en local—. Lo que nunca aparece es en dependencies, porque eso forzaría una segunda copia. La regla mental es limpia: dependencies para lo que es tuyo y puede duplicarse sin daño; peerDependencies para lo que debe ser único y compartido con quien te consume.

Los tres daños de incrustar

Conviene ver con nitidez qué rompes exactamente cuando empaquetas una dependencia que deberías haber externalizado, porque los tres daños son distintos y los tres son reales. El primero es la duplicación: si tu librería incrusta lodash y la app del consumidor también lo usa, el bundle final carga dos copias del mismo código. Multiplícalo por varias librerías que hacen lo mismo y el peso se dispara sin que nadie lo note hasta medir.

El segundo es el más insidioso: los singletons rotos. Ciertas librerías —React, Vue, el cliente de un store, un contexto de i18n— dependen de que exista una sola instancia en todo el árbol. Si tu librería trae su propia copia de React incrustada, tus componentes usan un React distinto del de la app, y cosas como los hooks o el Context fallan con errores desconcertantes que no apuntan a la causa. Es el bug clásico de “invalid hook call”: dos Reacts donde debía haber uno.

El tercero es que saboteas el tree shaking del consumidor. Si dejas lodash-es como external, quien te instala importa solo las funciones que tu código realmente usa y su bundler poda el resto. Si lo incrustas ya resuelto en tu dist, congelas esa decisión: el consumidor se traga lo que tú metiste, sin poder sacudir nada ni deduplicarlo contra su propia copia. Externalizar no es solo higiene de peso; es devolverle al consumidor el control sobre las dependencias que son, al fin y al cabo, suyas.

flowchart TD
A[tu libreria importa react] --> B{lo marcas external}
B -->|si| C[el import sale intacto]
C --> D[el consumidor conecta SU react]
D --> E[una sola instancia, hooks ok]
B -->|no, lo incrustas| F[tu dist trae su propio react]
F --> G[dos copias en el arbol]
G --> H[singleton roto: invalid hook call]
style E fill:#a6e3a1,color:#11111b
style H fill:#f38ba8,color:#11111b

Peers opcionales y la externalización automática

No toda peer dependency es obligatoria. A veces tu librería puede integrarse con otro paquete si está presente, pero funciona igual sin él —un adaptador que aprovecha un framework opcional, un plugin que mejora si detecta cierta librería—. Para ese caso, peerDependenciesMeta marca un peer como opcional, de modo que el gestor no avise si el consumidor no lo tiene instalado.

{
  "peerDependencies": {
    "react": ">=18",
    "redux": ">=5"
  },
  "peerDependenciesMeta": {
    "redux": { "optional": true }
  }
}

Aquí react es un peer obligatorio y redux uno opcional: tu librería lo usa si está, pero no rompe la instalación si falta. La contrapartida es que tu código debe comprobar en runtime si el peer opcional existe antes de tocarlo, porque su presencia dejó de estar garantizada. Es un contrato más flexible, pero también uno que traslada al autor la responsabilidad de degradar con elegancia cuando el peer no aparece.

En la práctica no mantienes la lista de externals a mano. Las herramientas de empaquetado de librerías —tsdown, unbuild— externalizan por defecto todo lo que figure en dependencies y peerDependencies, leyéndolo del propio manifiesto. Así, declarar bien tus dependencias no solo documenta el contrato: configura el build, porque la misma lista que el consumidor instalará es la que tu bundler deja fuera. Un manifiesto honesto produce, casi gratis, un dist correctamente externalizado.

El reverso de externalizar es que tu librería deja de garantizar por sí sola que la versión correcta esté presente: esa garantía se traslada al gestor de paquetes del consumidor, que resuelve tus peers contra el árbol completo y avisa si falta uno o si el rango no se satisface. Publicar con externals bien declarados es, en el fondo, delegar la resolución en quien tiene la vista completa del árbol —el único que puede deduplicar tu React con el de las otras diez librerías que también lo piden— en lugar de imponer tu copia a ciegas.