El manifiesto de una librería: exports, types, sideEffects, files y qué NO poner

Todo lo que has visto en este nivel converge en un solo archivo. Los formatos que ofreces, los externals que declaras, los tipos que publicas, la frontera de tu API: cada decisión termina escrita en el package.json, que deja de ser una lista de dependencias para revelarse como lo que de verdad es —el manifiesto de distribución de tu librería, el documento que el registro, los bundlers y los runtimes leen para saber cómo tratar tu paquete—. Y como todo manifiesto, se define tanto por lo que incluye como por lo que deja fuera. Saber qué campos poner es la mitad del oficio; saber qué campos y qué archivos no poner es la otra mitad, y la que separa un paquete profesional de uno que filtra sus tripas al mundo.

Los campos que firman el contrato

Un puñado de campos concentra todos los acuerdos del nivel. El exports es la pieza central: dibuja la frontera pública del paquete, mapea cada subpath a su archivo y sella todo lo que no aparece listado, de modo que nadie pueda acoplarse a tus internos. Dentro de él, la condición types apunta al .d.ts de cada entrada —siempre la primera de su rama— y las condiciones import y require sirven el formato correcto a cada consumidor. El sideEffects autoriza al bundler del consumidor a podar módulos enteros al declarar que importarlos no tiene efectos observables. Y type: module fija que tus .js son ESM.

{
  "name": "mi-lib",
  "version": "2.1.0",
  "type": "module",
  "sideEffects": false,
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./package.json": "./package.json"
  },
  "files": ["dist"]
}

Ese bloque es un manifiesto de librería moderna casi completo, y cada línea es un contrato distinto que ya conoces. Conviene además conservar los campos heredados como red de compatibilidad: main para el consumidor antiguo que no entiende exports, module para el bundler que busca el entry ESM, y types en la raíz para el resolvedor de tipos que no lee la condición. No contradicen a exports —lo respaldan— y su presencia es pura cortesía hacia herramientas que aún no implementan el estándar.

files: qué bytes viajan al registro

El campo files decide qué se publica, y es la primera línea de defensa contra un paquete inflado. Cuando publicas, npm no sube tu repositorio entero: sube una lista blanca definida por files —o, en su ausencia, todo lo que no excluya .npmignore, que es la política peligrosa por defecto—. Declarar files: ["dist"] dice con precisión “solo viaja mi salida compilada”, y todo lo demás —tu src, tus tests, tu configuración— se queda en el repositorio, donde pertenece.

La diferencia entre una lista blanca y una lista negra no es estética: es de seguridad y de peso. Con files enumeras lo que sí sale, de modo que un archivo nuevo que añadas al repo no se publica por accidente. Con .npmignore enumeras lo que no sale, y cualquier cosa que olvides añadir a esa lista se filtra al registro —un .env con secretos, un directorio de fixtures pesado, notas internas—. La regla de 2026 es tajante: usa files como lista blanca y trata todo lo demás como privado por defecto.

{
  "files": ["dist", "README.md"],
  "publishConfig": {
    "access": "public",
    "provenance": true
  }
}

Algunos archivos viajan siempre, los declares o no —el package.json, el README, el LICENSE—, así que no necesitas listarlos. Lo que sí conviene es verificar en seco qué acabará en el tarball antes de publicar: un empaquetado de prueba te muestra la lista exacta de archivos y su peso, y ahí se cazan de un vistazo el src que no querías subir o los sourcemaps que engordan el paquete sin aportar a quien lo instala.

Qué NO poner: el manifiesto por sustracción

Un manifiesto de librería se distingue tanto por su disciplina de exclusión como por sus campos. Lo primero que no debe salir son tus dependencias de desarrollo mal ubicadas: devDependencies no las instala el consumidor, así que todo lo que tu código necesite en runtime tiene que estar en dependencies o peerDependencies, nunca en devDependencies; y al revés, tu bundler, tu framework de test y tus linters jamás deben aparecer como dependencies, porque forzarían a cada consumidor a instalarlos.

Después vienen los campos y archivos que son asunto tuyo y de nadie más. Un package.json de aplicación suele acumular configuración de herramientas —bloques de tu bundler, de tu test runner, de tu linter, scripts de desarrollo—, y nada de eso tiene sentido en un paquete publicado: el consumidor no ejecuta tus scripts ni lee tu config. No es que rompan —muchos son inertes— sino que son ruido que ensancha la superficie, revela tu tooling interno y, en el peor caso, filtra rutas o nombres que preferirías no exponer.

Y lo más grave: lo que nunca, bajo ninguna circunstancia, debe viajar al registro.

• Secretos: un .env, un token en un archivo de config, credenciales en fixtures. El registro es público e inmutable; un secreto publicado está comprometido.
• El código fuente sin necesidad: salvo que quieras publicar src a propósito, tu TypeScript original y tus sourcemaps engordan el paquete sin que el consumidor los use.
• Artefactos de test y CI: fixtures pesados, snapshots, reportes de cobertura, configuración de pipelines. Nada de eso es tu librería.
• Los internos que exports debía sellar: si publicas dist entero pero tu exports no bloquea los subpaths internos, la frontera que dibujaste es de papel.

flowchart TD
P[package json de tu libreria] --> C[campos que firman el contrato]
C --> C1[exports: la frontera]
C --> C2[types: el contrato estatico]
C --> C3[sideEffects: autoriza la poda]
C --> C4[files: que bytes viajan]
P --> N[lo que NO debe salir]
N --> N1[secretos y env]
N --> N2[devDependencies como runtime]
N --> N3[config y scripts internos]
N --> N4[fuente y fixtures innecesarios]
style C fill:#a6e3a1,color:#11111b
style N fill:#f38ba8,color:#11111b

Los campos que identifican y acreditan

Más allá de los campos que cablean el build, un manifiesto de librería lleva otro grupo cuya función es identificar el paquete y acreditar su procedencia. El name y la version son su identidad en el registro; la license declara bajo qué términos se puede usar —omitirla no lo hace “más libre”, lo hace legalmente ambiguo, y muchas empresas rechazan de plano las dependencias sin licencia clara—; y repository, homepage y bugs conectan el paquete con su código y su soporte, algo que las herramientas de auditoría y los propios consumidores consultan antes de confiar en una dependencia.

{
  "name": "@scope/mi-lib",
  "version": "2.1.0",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/usuario/mi-lib.git"
  },
  "keywords": ["esm", "typescript", "tree-shaking"]
}

En 2026 este grupo incluye también la procedencia. Publicar con provenance vincula criptográficamente el tarball del registro con el commit y el pipeline de CI que lo produjeron, de modo que un consumidor puede verificar que el paquete que instala salió de verdad de tu repositorio y no de una máquina comprometida. Tras los ataques a la cadena de suministro de los últimos años, esa acreditación pasó de lujo a expectativa: un paquete sin procedencia verificable es, para muchos equipos, un paquete en el que no se confía.

El hilo que une identidad, licencia y procedencia es la confianza. Un desconocido que evalúa tu librería no puede leer todo tu código, así que se apoya en señales: que tenga licencia clara, que apunte a un repositorio auditable, que acredite su origen. Estos campos no cambian una línea de lo que tu código hace, pero cambian la disposición de alguien a instalarlo —y esa disposición es, al final, lo que decide si tu trabajo se usa o se descarta.