El campo exports: la frontera del paquete

Durante años un paquete de npm fue una carpeta abierta: cualquiera podía importar paquete/dist/internal/secreto.js y quedar atado a tus tripas. El campo exports cambió esa realidad. Convierte el package.json de un simple mapa de entrada en una frontera real: el autor declara exactamente qué es público y el runtime hace cumplir esa frontera. Es la pieza que convierte un directorio de archivos en un módulo de verdad.

De main a exports

El viejo campo main era una sola puerta y no impedía entrar por las ventanas: apuntaba al punto de entrada, pero nada frenaba un import a cualquier archivo del paquete. El campo exports (Node 12.7 en adelante, universal en 2026) redefine el paquete entero. En su forma más simple es azúcar para un único punto de entrada:

{
  "name": "mi-lib",
  "exports": "./dist/index.js"
}

La forma completa es un objeto de subpaths. La clave "." representa el entry principal, y es habitual re-exponer el propio package.json porque muchas herramientas lo leen en tiempo de ejecución:

{
  "exports": {
    ".": "./dist/index.js",
    "./package.json": "./package.json"
  }
}

Conviene entender que exports no borra a main: lo eclipsa. Un runtime que entiende exports lo usa y descarta main; una herramienta antigua que lo ignora cae en main como respaldo. Por eso muchos paquetes conservan main, module y types en la raíz junto a exports: son la red para consumidores que aún no implementan el estándar. La regla mental es que exports es la verdad para lo moderno y los campos sueltos son pura compatibilidad hacia atrás.

Hay un detalle operativo fácil de olvidar: exports apunta a archivos que deben existir en el paquete publicado, no en tu repositorio. Si el campo files o tu .npmignore excluye la carpeta dist, acabarás con un exports que apunta al vacío y un paquete que no resuelve nada tras instalarse. La ruta mapeada y la ruta empaquetada tienen que coincidir, y comprobarlo es trivial: empaqueta en seco y mira lo que sale.

Subpaths y patrones

Puedes publicar varios puntos de entrada nombrados y, para no listar archivo por archivo, usar un patrón comodín. El * no es un glob: es un marcador posicional que se sustituye literalmente por lo que el consumidor escriba.

{
  "exports": {
    ".": "./dist/index.js",
    "./utils": "./dist/utils/index.js",
    "./features/*": "./dist/features/*.js"
  }
}

Con ese patrón, mi-lib/features/auth resuelve a ./dist/features/auth.js sin que tengas que enumerar cada feature. Expones una carpeta completa de forma controlada y el resto del paquete permanece sellado. Cuando dos entradas encajan, gana siempre la más específica: una clave literal como ./utils tiene prioridad sobre un patrón que también la cubriría.

El comodín funciona en los dos lados de la correspondencia y debe cuadrar: lo que captura el * de la clave se sustituye literalmente en el * del valor. Esta misma mecánica gobierna la resolución de tipos cuando el patrón se combina con la condition types, de modo que un único patrón puede servir a la vez el JavaScript y sus declaraciones para toda una carpeta, sin duplicar entradas ni mantener dos mapas paralelos.

El árbol de decisiones completo, desde el especificador hasta el archivo o el error, es este:

flowchart TD
A[import de mi-lib mas un subpath] --> B[leer el campo exports]
B -->|subpath listado| C[servir la ruta mapeada]
B -->|coincide un patron| D[sustituir el comodin y servir]
B -->|mapeado a null| E[acceso bloqueado]
B -->|no aparece| F[error PACKAGE PATH NOT EXPORTED]

Encapsulación: lo que exports prohíbe

Aquí está la revolución, y no es mapear: es prohibir. En cuanto un paquete define exports, todo lo que no aparece listado se vuelve inaccesible. Un import "mi-lib/dist/internal/x.js" deja de funcionar y lanza ERR_PACKAGE_PATH_NOT_EXPORTED, aunque el archivo exista en disco. Puedes además vetar rutas de forma explícita mapeándolas a null:

{
  "exports": {
    ".": "./dist/index.js",
    "./features/*": "./dist/features/*.js",
    "./features/internal/*": null
  }
}

El patrón más específico gana también aquí: features/internal queda bloqueado pese a caer bajo features/*. Así abres una carpeta y, dentro de ella, cierras una subcarpeta.

El bloqueo tiene además una dimensión de seguridad que suele pasarse por alto. Si nadie puede importar tu-dep/dist/internal/parser.js, nadie puede acoplarse a sus detalles ni parchearlos desde fuera, lo que reduce la superficie de la cadena de suministro y hace que refactorizar el interior sea seguro. La encapsulación no es solo higiene de API: es también una línea de defensa contra el acoplamiento no deseado a las tripas de un paquete.

Cada subpath de exports es también una frontera para el tree-shaking y para las herramientas de análisis: al declarar puntos de entrada finitos y conocidos, el bundler sabe exactamente qué puede eliminar, y los reportes de tamaño pueden atribuir peso por entrada. Un paquete con exports bien granulado no solo es más seguro de mantener, sino más fácil de optimizar para quien lo consume.

Errores frecuentes