Dependencias compartidas: shared y singletons

La federación tiene un problema estructural: si el host trae su React y cada remote trae el suyo, el usuario descarga el mismo framework varias veces y, mucho peor, terminan conviviendo varias instancias de una librería que asume ser única. Hooks que fallan, contextos que no se ven, estados que se duplican. El campo shared existe para esto: declara qué dependencias viven en un ámbito común, con singleton para forzar una única instancia y una negociación de versiones que, en runtime, elige la copia que todos compartirán.

El problema: dos Reacts en la misma página

Sin shared, cada aplicación federada es autosuficiente: el host empaqueta React, y cada remote empaqueta el suyo. En una página que compone un host y tres remotes, el navegador puede acabar descargando cuatro copias del mismo framework. El desperdicio de bytes es lo de menos.

El daño real es semántico. Librerías como React, Vue o cualquier gestor de estado guardan estado a nivel de módulo: React lleva la cuenta del hook actual en una variable interna compartida por todo el árbol. Si en la misma página hay dos instancias de React —la del host y la del remote—, un componente del remote renderizado dentro del árbol del host llama a los hooks de su React, distinto del que gestiona el árbol. El resultado es el célebre error de hooks inválidos, contextos que aparecen vacíos y un instanceof que falla porque las clases vienen de módulos distintos.

// Sintoma clasico de dos instancias de React coexistiendo:
// "Invalid hook call", o un contexto que siempre da su valor por defecto
// aunque el Provider este claramente mas arriba en el arbol.

La lección es que ciertas dependencias no toleran duplicarse: no basta con que la versión sea la misma, tiene que ser la misma instancia cargada una sola vez. Compartir no es aquí una optimización de tamaño; es una condición de correctitud.

shared y el ámbito compartido

shared declara qué dependencias se ofrecen y se consumen desde un ámbito compartido (el share scope): un registro en runtime donde cada aplicación deposita las versiones que trae y del que toma las que necesita. En lugar de que cada bundle cargue su copia sin mirar a los lados, todos publican lo que tienen en ese registro común y la runtime decide, cuando alguien pide una dependencia, qué copia entregar.

// Tanto el host como cada remote declaran lo que comparten.
new ModuleFederationPlugin({
  name: "host",
  shared: {
    react: { singleton: true, requiredVersion: "^19.0.0" },
    "react-dom": { singleton: true, requiredVersion: "^19.0.0" },
  },
});

El mecanismo es elegante: una dependencia compartida se carga como un chunk asíncrono aparte, no fundido en el bundle principal. Así, cuando la página arranca, la runtime puede mirar el ámbito compartido, ver qué copias hay disponibles y cargar solo una, evitando la descarga redundante y, con singleton, la coexistencia de instancias.

singleton y la negociación de versiones

Compartir plantea de inmediato una pregunta: si el host trae React 19.1 y un remote pide React 19.0, ¿cuál se usa? Aquí entran tres opciones que gobiernan la política.

singleton: true impone que solo puede haber una instancia en toda la página. La runtime elige la versión más alta compatible entre las que se ofrecen y la sirve a todos; si alguien pedía una incompatible, emite un aviso pero sigue con la única instancia, porque tener dos rompería más que una versión ligeramente distinta. Es obligatorio para React, Vue y cualquier librería con estado de módulo.

requiredVersion declara qué rango de versiones acepta un consumidor, en semver. La runtime lo usa para negociar: busca en el ámbito compartido la versión más alta que satisfaga todos los rangos requeridos.

strictVersion: true convierte el aviso en error: si no hay una versión que cumpla el rango, la carga falla en vez de degradar. Útil cuando una incompatibilidad es preferible detectarla ruidosamente a arrastrarla en silencio.

flowchart TD
H[host ofrece react 19.1] --> S[ambito compartido]
R1[remote A pide react 19.0] --> S
R2[remote B pide react 19.x] --> S
S -->|elige la mas alta compatible| U[una sola instancia: react 19.1]
style S fill:#f9e2af,color:#11111b
style U fill:#a6e3a1,color:#11111b
style H fill:#cba6f7,color:#11111b

eager y el coste de compartir

Compartir no es gratis. Una dependencia compartida se carga como chunk asíncrono, lo que introduce un pequeño baile de resolución antes de que esté disponible. eager: true la incluye en el chunk inicial en vez de diferirla, eliminando ese baile a costa de renunciar a la carga perezosa: la dependencia viaja siempre, la use o no esa ruta. Se reserva para la dependencia raíz que sabes que todos necesitan desde el primer instante.

// eager: la comparte pero la mete en el bundle inicial, sin chunk async
shared: {
  react: { singleton: true, eager: true, requiredVersion: "^19.0.0" },
}

Y no todo debe compartirse. Compartir tiene sentido para lo que es pesado y común —el framework, la librería de UI, el cliente de datos— y donde una sola instancia es una condición de correctitud. Para una utilidad pequeña y sin estado, compartir puede costar más —en coordinación de versiones y en complejidad— de lo que ahorra en bytes. La regla: comparte lo que debe ser único o es caro de duplicar; deja que cada quien empaquete lo trivial.