Abres un borrador de página web en el editor para probar rápido una idea en el navegador sin empaquetador y conectas una librería a través de una red de entrega de contenidos (CDN). Escribes en la línea de importación el nombre del paquete, indicas el archivo de estilos y recibes en consola un error 404 Not Found. Toca abrir el árbol de la release y añadir a mano en medio de la URL una carpeta técnica, convirtiendo el enlace en algo aparatoso como https://cdn.jsdelivr.net/npm/ie-page-transitions@0.0.1/src/ie-page-transitions.css.
Este detalle del ecosistema JavaScript siempre me ha sorprendido: ¿por qué quien toma un paquete listo para usar tiene que saber en qué carpeta guardó el autor los archivos compilados? El ingeniero de Google Chrome Developer Relations Bramus Van Damme mostró en el blog Bram.us cómo usar una función integrada de npm CLI para subir al registro únicamente el contenido del directorio ./dist, de modo que los módulos se importen directamente desde la raíz del paquete y el repositorio mantenga el orden.
Por qué la carpeta de compilación se filtra en las URLs públicas de las librerías
En un proyecto moderno de JavaScript o TypeScript el código vive en dos estantes: en ./src están los fuentes y en ./dist el compilador deja los scripts .js listos, las declaraciones de tipos .d.ts y los estilos .css. Cuando ejecutas npm publish desde la raíz del proyecto, la utilidad empaqueta el directorio actual completo junto con su estructura de carpetas anidadas.
Es como entregarle al comprador una tostadora no en su caja de tienda, sino dentro de un cajón metálico de la mesa de montaje con el rótulo «Taller de producto terminado». Bramus pone el ejemplo de la primera versión de su paquete ie-page-transitions (0.0.1), donde los cuatro archivos de trabajo —ie-page-transitions.css, ie-page-transitions.mpa.js, ie-page-transitions.shared.js y ie-page-transitions.spa.js— se subieron al registro dentro del directorio ./src.
En un entorno Node.js o al compilar con un bundler, esta estructura la oculta el campo exports del package.json raíz. Funciona como un recepcionista: la petición import styles from 'ie-page-transitions/css' with { type: "css" } se redirige sin que se note a la ruta interna ./src/ie-page-transitions.css. Pero al cargar el paquete en el navegador desde un CDN público el disfraz desaparece: el servidor lee el archivo comprimido por sus rutas físicas y la carpeta ./src/ o ./dist/ queda expuesta en la URL pública.
En el intento de quitar ese prefijo sobrante, los autores suelen irse al extremo opuesto: renuncian a ./dist y vuelcan los archivos compilados .js, .d.ts y .map directamente en la raíz del repositorio. En el escaparate del registro las rutas quedan cortas, pero dentro del proyecto empieza el caos: los artefactos de compilación se mezclan con configuraciones, pruebas y código fuente, ensuciando el árbol de trabajo en Git.
Cómo funciona publicar un directorio anidado y por qué el paquete pierde su pasaporte
Para no convertir el repositorio en un vertedero y ofrecer hacia fuera una interfaz limpia, basta con cambiar el punto de empaquetado. El comando npm publish acepta la ruta a la carpeta destino como argumento: npm publish ./dist.
Veamos cómo actúa el empaquetador con esa llamada:
- Si le pasas a la utilidad la ruta
./dist, entoncesnpmdeja de empaquetar la raíz del repositorio y designa el directorio./distcomo la cima del archivo publicado. - Si
./distpasa a ser la cima del archivo, entonces todos los archivos compilados dentro quedan en el nivel superior del paquete: así publicó Bramus las libreríashic-pageflip,mermaid-elementyrich-input, reduciendo la importación por CDN a un limpioimport { PageFlip } from 'https://cdn.jsdelivr.net/npm/hic-pageflip'. - Pero si el empaquetador ignora todo lo que queda fuera de
./dist, entonces al enviarse el paquete pierde su pasaporte: los archivospackage.json,README.mdyLICENSEque se quedaron un piso más arriba en la raíz del repositorio.
Aquí surge la segunda trampa. Supongamos que simplemente copiaste el package.json raíz dentro de ./dist. En el archivo original los puntos de entrada están escritos respecto a la raíz del repositorio: "main": "./dist/index.js" y "exports": { ".": "./dist/index.js", "./submodule": "./dist/submodule.js" }. Si subes ese manifiesto dentro de ./dist, tras instalar el paquete Node.js buscará los archivos en ./dist/index.js ya respecto a la nueva raíz, es decir, apuntará a la ruta inexistente ./dist/dist/index.js, y la importación se romperá.
En el gestor de paquetes pnpm esto lo resuelve la opción "publishConfig": { "directory": "dist" } (sobre otras herramientas para trabajar con el registro escribimos en el análisis del lanzamiento de pnpm 12.13.0). Sin embargo, el cliente estándar npm, pese a una década de peticiones de la comunidad, no soporta el campo publishConfig.directory, por lo que hay que integrar la preparación de ./dist en el paso de compilación.
Generación automática de un manifiesto limpio y copia de metadatos a dist
Veamos con el ejemplo de un paquete de utilidades cómo automatizar la preparación de la carpeta ./dist tras compilar. Escribimos un script scripts/postbuild.js usando los módulos integrados node:fs y node:path que copia la documentación con la licencia, limpia package.json de secciones internas y reescribe las rutas en main, module, types y exports respecto a la nueva raíz:
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const rootDir = path.resolve(__dirname, '..');
const distDir = path.join(rootDir, 'dist');
for (const file of ['README.md', 'LICENSE']) {
const srcPath = path.join(rootDir, file);
if (fs.existsSync(srcPath)) {
fs.copyFileSync(srcPath, path.join(distDir, file));
}
}
const pkgPath = path.join(rootDir, 'package.json');
const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
delete pkg.scripts;
delete pkg.devDependencies;
const distPkg = JSON.stringify(pkg, null, 2).replaceAll('./dist/', './') + '\n';
fs.writeFileSync(path.join(distDir, 'package.json'), distPkg, 'utf8');
Al ejecutarse, el bucle copia README.md y LICENSE junto a los módulos compilados para que el escaparate web del registro muestre la documentación y el paquete conserve su validez legal. Después el script lee el package.json raíz, con el operador delete elimina los bloques scripts y devDependencies que no necesitan los consumidores de la librería, y con replaceAll('./dist/', './') recorta el prefijo de la carpeta de compilación en todos los puntos de entrada, convirtiendo "./dist/index.js" y "./dist/submodule.js" en rutas directas "./index.js" y "./submodule.js".
Para que el script se ejecute automáticamente después de compilar, añade al package.json raíz el hook "postbuild": "node scripts/postbuild.js". Y si el compilador genera mapas de código fuente, échale un vistazo a nuestro artículo sobre cuándo tienen sentido los source maps en paquetes npm y cómo reducir el volumen de JavaScript, para no inflar el paquete con archivos de depuración.
Al copiar metadatos a ./dist, nunca traslades ahí archivos .env, un .npmrc local con el token NODE_AUTH_TOKEN ni configuraciones de CI/CD. Si tu paquete distribuye comandos de consola mediante la sección bin, asegúrate de que sus rutas en dist/package.json también estén ajustadas respecto a ./dist.
Defensa contra la memoria muscular y verificación del archivo con npm pack
Incluso con el script listo queda el riesgo de la costumbre: si por inercia tecleas npm publish desde la raíz del proyecto, la utilidad ejecutará la compilación pero subirá al registro todo el directorio raíz en vez de ./dist. Para blindarse ante eso, Bramus convierte el hook "prepublishOnly" en un fusible "if [ -z $PUBLISH ]; then echo 'ERROR: Use npm run pub' && exit 1; fi", y traslada la publicación al comando "pub": "PUBLISH=true npm run build && npm publish ./dist --access public".
Si se llama por accidente a npm publish, la variable de entorno $PUBLISH está vacía (-z $PUBLISH), así que el script devuelve exit 1 y bloquea el envío. En cambio npm run pub pasa la bandera PUBLISH=true, lanza la compilación con postbuild.js y publica solo la carpeta ./dist. En pipelines de equipo, este enfoque complementa la entrega aislada de artefactos explicada en la guía sobre publicación segura de paquetes npm y protección de la cadena de suministro.
Antes del primer envío comprueba el contenido del archivo en modo simulación con npm publish ./dist --dry-run o mediante npm pack ./dist --dry-run. La utilidad generará el paquete sin subirlo a la red y mostrará la lista Tarball Contents: para hic-pageflip (1.0.1) el informe muestra un archivo hic-pageflip-1.0.1.tgz de 3.2 kB (9.1 kB descomprimido) con 5 archivos en la propia raíz: LICENSE (1.1kB), README.md (1.8kB), index.js (850B), package.json (1.2kB) y core/engine.js (4.2kB). También puedes ejecutar npm pack ./dist y descomprimir el archivo con tar -xzf my-package-1.0.0.tgz para comprobar personalmente la limpieza de la estructura.
No te preocupes si en tus librerías actuales las rutas de importación todavía contienen /dist: no hace falta dejarlo todo y rehacer todos los repositorios viejos en una sola noche. Empieza en la próxima actualización planificada de cualquier paquete pequeño: añade el breve script de preparación del manifiesto, verifica la lista de archivos con npm pack ./dist --dry-run y pasa a la publicación limpia cuando compruebes que cada módulo está en su sitio.


