package.json "type" y exports

Los campos "type" y "exports" de package.json definen cómo Node resuelve tu paquete; reemplazan los campos main ambiguos y bloquean los archivos internos de las importaciones profundas.

Receta

{
  "name": "@acme/billing-sdk",
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./package.json": "./package.json"
  },
  "files": ["dist"]
}

Cuándo usar esto:

• Publicar paquetes internos de monorepo en npm o Verdaccio
• Bloquear a los consumidores para que no import '@acme/pkg/src/internal/foo.js'
• Librerías duales CJS/ESM durante la transición del ecosistema
• Herramientas que respetan exports (TypeScript 5.6+, webpack 5, Node 24)

Ejemplo práctico

{
  "name": "@acme/shared-types",
  "type": "module",
  "exports": {
    ".": "./dist/index.js",
    "./users": "./dist/users.js",
    "./package.json": "./package.json"
  },
  "imports": {
    "#internal/*": "./src/internal/*.js"
  }
}

// consumer.ts
import { UserDto } from '@acme/shared-types/users';

// solo dentro del paquete @acme/shared-types
import { helper } from '#internal/helper.js';

Lo que esto demuestra:

• La lista blanca "exports" es la única superficie importable; las rutas profundas fallan sin una coincidencia
• Las exportaciones de subrutas (./users) publican puntos de entrada enfocados sin la sobrecarga de los barrel files
• El campo "imports" mapea alias internos (#internal/*) para atajos privados del paquete
• Exportación explícita de "./package.json" cuando las herramientas necesitan leer metadatos

A fondo

Cómo funciona

• "type": "module" - Los archivos .js son ESM; usa .cjs para CommonJS intencional.
• "exports" - Las claves del objeto son subrutas públicas; los valores son archivos de destino u objetos condicionales.
• Condiciones - "import", "require", "node", "default" seleccionan variantes por cada resolvedor.
• Sin coincidencia, sin acceso - Importar rutas no exportadas lanza ERR_PACKAGE_PATH_NOT_EXPORTED.

Formas de exportación comunes

Notas de TypeScript

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  }
}

Empareja la condición "types" (o typesVersions) para que los consumidores obtengan las tipificaciones que coincidan con la exportación.

Errores comunes

• Solo establecer main sin exports - las herramientas modernas aún pueden permitir importaciones profundas. Solución: añade "exports" para encapsular.
• Olvidar .js en los destinos de exportación - debe apuntar a archivos que existan después de la compilación. Solución: comprueba en CI que dist coincida con exports.
• Peligro de paquete dual - instancias separadas de import y require rompen instanceof. Solución: prefiere solo ESM para paquetes de aplicaciones; documenta para librerías.
• Exportaciones con comodines demasiado amplias - "./src/*" expone internos. Solución: exporta solo artefactos de dist.
• Protocolo de espacio de trabajo de monorepo sin compilar - los consumidores resuelven incorrectamente a la fuente de TS. Solución: exports apuntan a dist compilado en paquetes publicados.

Alternativas

Preguntas frecuentes

Relacionado

• Módulos ES (import) - Sintaxis ESM que consume exportaciones
• Algoritmo de resolución de módulos - Orden de resolución
• Interoperabilidad CJS ↔ ESM - Exportaciones de doble condición
• Compartir tipos con el frontend - Paquetes de monorepo

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.