Diseñar la superficie: entrada y subpaths

Publicar una librería en 2026 no es subir una carpeta: es firmar un contrato. El campo exports es el instrumento donde ese contrato queda escrito. Como autor decides, ruta por ruta, qué es superficie pública —lo que prometes mantener— y qué es interior privado —lo que te reservas el derecho de reescribir mañana—. Dominar exports desde el lado de quien publica separa la librería que puedes evolucionar con confianza de la jaula que tus propios usuarios construyen importando tus tripas.

El paquete como contrato, no como carpeta

Antes de exports, la superficie pública de una librería no la decidía su autor: la decidían sus usuarios. El campo main señalaba una única puerta, pero nada impedía que alguien importara mi-lib/dist/internal/parser.js y quedara acoplado a un archivo que tú considerabas privado. Esa es la ley de Hyrum llevada al empaquetado: con suficientes consumidores, cada comportamiento observable de tu paquete —cada ruta que resuelve— se convierte en una dependencia de alguien, la hubieras diseñado o no.

El campo exports invierte esa dinámica. En cuanto lo declaras, el paquete pasa de ser una carpeta abierta a ser un módulo sellado: solo las rutas que enumeras son alcanzables desde fuera, y todo lo demás lanza ERR_PACKAGE_PATH_NOT_EXPORTED aunque el archivo exista en disco. La superficie deja de ser accidental y pasa a ser un acto de diseño deliberado, verificado por el runtime en cada resolución.

Para un autor, ese cambio tiene una consecuencia enorme: puedes evolucionar. Todo lo que no está en exports es tuyo para renombrar, mover o borrar sin que sea un cambio mayor, porque el runtime garantiza que nadie podía depender de ello. El contrato que firmas es exactamente el conjunto de claves de tu exports, ni una ruta más.

La entrada principal y los subpaths nombrados

La forma mínima de exports es azúcar para un único punto de entrada. La forma completa es un objeto de subpaths donde la clave "." representa la entrada principal, la que resuelve al importar el paquete por su nombre desnudo. Es habitual re-exponer el propio package.json, porque muchas herramientas lo leen en tiempo de ejecución y sin esa línea también quedaría sellado:

{
  "name": "@acme/ui",
  "exports": {
    ".": "./dist/index.js",
    "./package.json": "./package.json"
  }
}

A partir de ahí, cada subpath nombrado es una decisión de arquitectura. Un ./utils, un ./client y un ./server no son solo rutas: son la manera de partir tu librería en fronteras que el usuario importa por separado. Diseñar buenos subpaths es diseñar buena API:

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

Hay aquí una tensión de diseño que todo autor debe resolver: el barril único frente a los subpaths granulares. Concentrar todo en la entrada "." con un index.js que reexporta el paquete entero es cómodo de documentar, pero fuerza al bundler del consumidor a analizar todo el grafo para eliminar lo que no usa, y un solo reexport mal marcado arrastra dependencias enteras. Ofrecer subpaths finos —un punto de entrada por función pesada— le da al consumidor fronteras naturales de tree-shaking y de carga diferida. En 2026 la buena práctica para librerías grandes es exponer subpaths por dominio, no un único barril monolítico.

Patrones y el sellado de lo interno

Enumerar cien componentes uno a uno es insostenible. El comodín * resuelve familias enteras de subpaths, y conviene entenderlo bien: no es un glob, es un marcador posicional que se sustituye literalmente por lo que el consumidor escriba, en la clave y en el valor a la vez. Con él expones una carpeta completa de forma controlada mientras el resto del paquete permanece sellado:

{
  "exports": {
    ".": "./dist/index.js",
    "./components/*": "./dist/components/*.js",
    "./components/internal/*": null,
    "./package.json": "./package.json"
  }
}

@acme/ui/components/button resuelve a ./dist/components/button.js sin listar cada componente. Cuando dos entradas encajan, gana siempre la más específica: por eso ./components/internal/* mapeado a null bloquea esa subcarpeta pese a caer bajo ./components/*. Así abres una carpeta y, dentro de ella, cierras una habitación. El bloqueo tiene además una dimensión de cadena de suministro: si nadie puede importar tus internos, nadie puede acoplarse a ellos ni parchearlos desde fuera.

flowchart TD
A[libreria con muchos archivos internos] --> B[definir el campo exports]
B --> C[entrada principal punto]
B --> D[subpaths nombrados como utils]
B --> E[patron de carpeta components]
B --> F[todo lo demas sellado]
F --> G[refactor libre sin romper semver]
style C fill:#89b4fa,color:#11111b
style E fill:#cba6f7,color:#11111b
style F fill:#f38ba8,color:#11111b
style G fill:#a6e3a1,color:#11111b

Una última herramienta para el autor es la self-reference: dentro del propio paquete puedes importar por tu nombre, @acme/ui/utils, y la resolución pasa por exports igual que para un consumidor externo. Eso te permite probar tu propia frontera desde tus tests, comprobando que lo que crees público lo es y que lo que sellaste está de verdad cerrado, antes de que un usuario lo descubra por ti.

Las decisiones recurrentes de diseño, condensadas en cuatro reglas que separan una superficie madura de una improvisada: