El dual package hazard: dos instancias

Hay un bug que no deja stack trace legible, no lanza excepción y hace dudar de tu propia cordura: un instanceof que devuelve falso cuando debería ser cierto, un contexto de React vacío sin razón, un singleton que de pronto tiene dos vidas. Casi siempre la causa es la misma y no está en tu lógica, sino en la resolución de módulos. Es el dual package hazard: el mismo paquete cargado dos veces, una por ESM y otra por CommonJS, generando dos identidades para lo que debería ser una. Entenderlo es dejar de perseguir fantasmas.

La identidad de un módulo es su ruta resuelta

La clave para entender todo el problema es una sola idea: un runtime cachea los módulos por su ruta resuelta, y esa ruta es su identidad. Dos especificadores que resuelven al mismo archivo comparten una única instancia evaluada; dos especificadores que resuelven a archivos distintos son, para el runtime, dos módulos diferentes con estado independiente, aunque su código fuente sea idéntico.

Aquí es donde el dual package tiende su trampa. Un paquete que publica un build ESM y otro CommonJS tiene dos archivos distintos para el mismo módulo lógico. Si en un mismo proceso una parte del grafo llega a él por import —cargando el .js ESM— y otra parte llega por require —cargando el .cjs—, el runtime evalúa los dos archivos y mantiene dos instancias separadas. No hay ningún mecanismo que las reconcilie: son, literalmente, dos módulos.

{
  "name": "@acme/store",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}

Este exports es impecable —publint lo aprueba sin una queja— y sin embargo es la condición exacta del peligro. ./dist/index.js y ./dist/index.cjs son dos rutas, luego dos identidades. Basta con que la aplicación importe el paquete como ESM y una de sus dependencias lo requiera como CommonJS —algo que ocurre a diario en un grafo real y mixto— para que ambos archivos se evalúen y el estado se parta en dos. El autor no ve nada raro: el hazard no está en su código, está en la topología de quién lo carga y cómo, que él no controla.

flowchart TD
A[mismo paquete logico en el grafo] --> B[una rama llega por import]
A --> C[otra rama llega por require]
B --> D[instancia ESM con su estado]
C --> E[instancia CJS con su estado]
D --> F[dos singletons y instanceof roto]
E --> F
style D fill:#89b4fa,color:#11111b
style E fill:#fab387,color:#11111b
style F fill:#f38ba8,color:#11111b

Los síntomas: estado que se bifurca

El daño aparece siempre que el módulo mantiene algo con identidad o estado. Un singleton pensado para existir una vez existe dos veces, cada copia con su propio estado, y las escrituras de una no las ve la otra. Un caché se ignora porque cada instancia consulta el suyo. Una configuración global aparece vacía en un lado porque se inicializó en el otro.

El síntoma más desconcertante es el instanceof roto. Cuando una clase se define en ambas copias del módulo, un objeto creado por la copia ESM no es instancia de la clase de la copia CommonJS: son dos clases distintas que comparten nombre y código pero no identidad. Comparaciones de identidad que deberían ser triviales empiezan a fallar sin motivo aparente.

Un caso especialmente traicionero son las librerías con estado de contexto, como React o los clientes de bases de datos y de i18n. Si la aplicación carga una copia y una dependencia carga la otra, el proveedor y el consumidor viven en instancias distintas y la comunicación entre ellos, que depende de compartir una referencia global, simplemente no ocurre. El componente se renderiza, no lanza error, y el contexto llega vacío.

Las estrategias de 2026 para evitarlo

La buena noticia es que en 2026 el problema tiene soluciones claras, y la mejor es no crearlo. La lista, de la más robusta a la más quirúrgica:

Cuando el dual build es inevitable, la técnica del núcleo compartido aísla el riesgo. La idea es que el estado con identidad viva en un único módulo interno —normalmente CommonJS, para que ambas caras puedan cargarlo por igual— y que los dos builds públicos, el ESM y el CJS, no dupliquen ese estado sino que lo reexporten. El singleton existe una sola vez, en el núcleo, y las dos fachadas apuntan a él:

// core.cjs  →  el estado vive aqui, una sola vez
let instancia;
module.exports.getStore = () => (instancia ??= crearStore());

// index.js (ESM)  y  index.cjs (CJS) reexportan el mismo nucleo
export { getStore } from "./core.cjs";

Cuando sospechas que el hazard ya está ocurriendo, una sonda barata lo confirma: registra la instancia en el registro global de símbolos y avisa si alguien la puso antes que tú. Dos cargas del mismo módulo dispararán el aviso, porque el Symbol.for es compartido entre ambas copias aunque cada una tenga su propio estado:

const MARCA = Symbol.for("@acme/store/instancia");
if (globalThis[MARCA]) {
  console.warn("@acme/store cargado dos veces: probable dual package hazard");
}
globalThis[MARCA] = true;

La condition module-sync (Node 22 en adelante) ataca la raíz de otra forma. Permite declarar un ESM que Node puede cargar de forma síncrona incluso desde un require, de modo que el consumidor CommonJS y el consumidor ESM acaban en el mismo archivo en lugar de en dos:

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "module-sync": "./dist/index.js",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}

Con module-sync sirviendo el mismo archivo ESM a ambas vías, hay una sola instancia y el estado no se puede bifurcar. Combinada con require(esm), apunta al mismo destino que la estrategia ESM-only: un único artefacto, una única identidad. La require explícita queda solo como respaldo para runtimes que aún no reconozcan module-sync.