Salida dual de paquetes ESM y CJS

ESM (ECMAScript Modules) es el estándar oficial de módulos de JavaScript que utiliza la sintaxis import y export. ESM se puede analizar estáticamente: los empaquetadores pueden determinar en tiempo de compilación exactamente qué exportaciones se utilizan, lo que permite aplicar tree-shaking. Tanto los navegadores modernos como Node.js admiten ESM de forma nativa.

CJS (CommonJS) utiliza la sintaxis require() y module.exports. Fue el sistema de módulos original de Node.js y todavía se necesita para mantener la compatibilidad con entornos antiguos de Node.js, con Jest (que históricamente utilizaba CJS) y con el código que usa require(). CJS se evalúa dinámicamente, lo que dificulta el tree-shaking.

Un paquete moderno de npm debería distribuir ESM y CJS para maximizar la compatibilidad. Los consumidores de ESM (Vite, Next.js y empaquetadores modernos) obtienen importaciones compatibles con tree-shaking. Los consumidores de CJS (scripts antiguos de Node.js y Jest sin configuración) obtienen compatibilidad con require(). El campo exports de package.json indica a Node y a los empaquetadores qué formato deben utilizar.

El campo exports de package.json es la forma moderna de definir puntos de entrada condicionales. Ejemplo: { '.': { 'import': './dist/esm/index.js', 'require': './dist/cjs/index.js', 'types': './dist/esm/index.d.ts' } }. Los empaquetadores y Node.js 12+ leen exports para seleccionar automáticamente el formato correcto.

Las herramientas antiguas no entienden el campo exports. Para mantener la compatibilidad, establezca también: main, apuntando a la salida CJS (respaldo heredado para require de Node), y module, apuntando a la salida ESM (una indicación para webpack/rollup, no estándar pero ampliamente compatible). Las herramientas modernas prefieren exports; las herramientas antiguas recurren a main/module.

Establecer "type": "module" en package.json hace que todos los archivos .js del paquete se traten como ESM. Si distribuye ambos formatos, necesitará extensiones explícitas: use .mjs para los archivos ESM y .cjs para los archivos CJS cuando type sea module, o al contrario. tsup lo gestiona automáticamente.

Usar las extensiones de archivo .mjs (ESM) y .cjs (CJS) marca explícitamente el formato, independientemente del campo type. Esto evita ambigüedades. tsup puede generar: index.js (ESM) y index.cjs (CJS) cuando format es ['esm', 'cjs'] y no se establece ningún campo type, siguiendo la convención más común.

Cuando un paquete proporciona los formatos ESM y CJS, el empaquetador del consumidor podría cargar ambas versiones en el mismo proceso; por ejemplo, la versión ESM para la aplicación principal y la versión CJS para una prueba de Jest. Si el paquete tiene estado a nivel de módulo, como un contexto de React, ambas instancias tendrán estados independientes. Este es el riesgo de los paquetes duales.

Para mitigar este riesgo, mantenga el estado a nivel de módulo fuera de su biblioteca (no utilice patrones singleton), use las condiciones de exports con precisión para garantizar que solo se cargue un formato y documente que las pruebas deben configurar su empaquetador para usar ESM. Este riesgo afecta principalmente a las bibliotecas con singletons compartidos.

Verifique que ambos formatos funcionen después de la compilación. Pruebe CJS: node -e "const lib = require('./dist/cjs/index.js'); console.log(lib)". Pruebe ESM: node --input-type=module --eval "import { Component } from './dist/esm/index.js'; console.log(Component)". Ambos deben resolverse sin errores antes de publicar.

El campo exports admite múltiples puntos de entrada: { '.': { import: './dist/esm/index.js', require: './dist/cjs/index.js' }, './utils': { import: './dist/esm/utils.js', require: './dist/cjs/utils.js' } }. Los consumidores pueden importar desde 'your-lib' o 'your-lib/utils' y obtener el formato correcto.

ESM utiliza import/export y permite aplicar tree-shaking. CJS utiliza require() para mantener la compatibilidad con Node.js. Distribuya ambos mediante el campo exports de package.json, con las condiciones import/require. Respaldos heredados: main (CJS) y module (ESM). Use las extensiones .mjs/.cjs o type: module para marcar explícitamente el formato. Pruebe ambos formatos con la CLI de node después de compilar. Tenga cuidado con el riesgo de los paquetes duales cuando utilice estado de singleton.