Открываешь в редакторе черновик веб-страницы, чтобы быстро проверить идею в браузере без сборщика, и подключаешь библиотеку через сеть доставки контента (CDN). Пишешь в строке импорта имя пакета, указываешь файл стилей — и получаешь в консоли ошибку 404 Not Found. Приходится открывать дерево релиза и вручную дописывать в середину адреса техническую папку, превращая ссылку в громоздкую конструкцию вроде https://cdn.jsdelivr.net/npm/ie-page-transitions@0.0.1/src/ie-page-transitions.css.
Меня эта деталь в экосистеме JavaScript всегда удивляла: почему человек, который берет готовый пакет для работы, вообще должен знать, в какую папку автор складывал скомпилированные файлы? Инженер Google Chrome Developer Relations Брамус Ван Дамме в блоге Bram.us показал, как с помощью штатной возможности npm CLI выгружать в реестр только содержимое каталога ./dist, чтобы модули импортировались напрямую из корня пакета, а в репозитории сохранялся порядок.
Почему папка сборки просачивается в публичные адреса библиотек
В современном проекте на JavaScript или TypeScript код живет на двух полках: в ./src лежат исходники, а в ./dist компилятор складывает готовые скрипты .js, декларации типов .d.ts и стили .css. Когда ты вызываешь npm publish из корня проекта, утилита упаковывает текущий каталог целиком вместе с вложенной структурой папок.
Это все равно что доставить покупателю тостер не в магазинной коробке, а прямо в железном ящике со сборочного стола с надписью «Цех готовой продукции». Брамус приводит пример с первой версией своего пакета ie-page-transitions (0.0.1), где все четыре рабочих файла — ie-page-transitions.css, ie-page-transitions.mpa.js, ie-page-transitions.shared.js и ie-page-transitions.spa.js — уехали в реестр внутри каталога ./src.
В среде Node.js или при сборке бандлером эту структуру прячет поле exports в корневом package.json. Оно работает как администратор на ресепшене: запрос import styles from 'ie-page-transitions/css' with { type: "css" } незаметно перенаправляется по внутреннему адресу ./src/ie-page-transitions.css. Но при загрузке пакета в браузере через публичный CDN маскировка пропадает: сервер читает архив по физическим путям, и папка ./src/ или ./dist/ вываливается в публичный адрес.
В попытке убрать лишний префикс авторы нередко впадают в крайность — отказываются от ./dist и выгружают скомпилированные файлы .js, .d.ts и .map прямо в корень репозитория. На витрине реестра пути становятся короткими, но внутри проекта начинается хаос: артефакты сборки перемешиваются с конфигами, тестами и исходниками, захламляя рабочее дерево в Git.
Как работает публикация вложенного каталога и почему пакет теряет паспорт
Чтобы не превращать репозиторий в свалку и выдавать наружу чистый интерфейс, достаточно изменить точку упаковки. Команда npm publish принимает путь к целевой папке как аргумент: npm publish ./dist.
Посмотрим, как работает архиватор при таком вызове:
- Если передать утилите путь
./dist, тоnpmперестает упаковывать корень репозитория и назначает каталог./distвершиной публикуемого архива. - Если
./distстановится вершиной архива, то все собранные внутри него файлы ложатся на верхний уровень пакета — так Брамус опубликовал библиотекиhic-pageflip,mermaid-elementиrich-input, сократив импорт через CDN до чистогоimport { PageFlip } from 'https://cdn.jsdelivr.net/npm/hic-pageflip'. - Но если архиватор игнорирует всё за пределами
./dist, то пакет при отправке лишается своего паспорта — файловpackage.json,README.mdиLICENSE, оставшихся этажом выше в корне репозитория.
Здесь возникает вторая ловушка. Допустим, ты просто скопировал корневой package.json внутрь ./dist. В исходном файле точки входа записаны относительно корня репозитория: "main": "./dist/index.js" и "exports": { ".": "./dist/index.js", "./submodule": "./dist/submodule.js" }. Если отправить такой манифест внутри ./dist, то после установки пакета Node.js начнет искать файлы по адресу ./dist/index.js уже относительно нового корня — то есть обратится к несуществующему пути ./dist/dist/index.js, и импорт сломается.
В пакетном менеджере pnpm эту задачу решает настройка "publishConfig": { "directory": "dist" } (о других инструментах работы с реестром мы писали в разборе релиза pnpm 12.13.0). Однако стандартный клиент npm, несмотря на десятилетние просьбы сообщества, поле publishConfig.directory не поддерживает — поэтому подготовку ./dist нужно встроить в шаг сборки.
Автоматическая сборка чистого манифеста и перенос метаданных в dist
Разберем на примере пакета утилит, как автоматизировать подготовку папки ./dist после компиляции. Напишем скрипт scripts/postbuild.js на встроенных модулях node:fs и node:path, который копирует документацию с лицензией, очищает package.json от служебных секций и переписывает пути в main, module, types и exports относительно новой вершины:
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');
При запуске цикл копирует README.md и LICENSE рядом со скомпилированными модулями, чтобы веб-витрина реестра отображала документацию, а пакет сохранял юридическую чистоту. Далее скрипт считывает корневой package.json, оператором delete вычищает блоки scripts и devDependencies, не нужные потребителям библиотеки, а вызовом replaceAll('./dist/', './') срезает префикс папки сборки во всех точках входа — превращая "./dist/index.js" и "./dist/submodule.js" в прямые пути "./index.js" и "./submodule.js".
Чтобы сценарий срабатывал автоматически после компиляции, добавь в корневой package.json хук "postbuild": "node scripts/postbuild.js". А если компилятор генерирует карты исходного кода, загляни в наш материал о том, когда source maps в npm-пакетах оправданы и как сократить объем JavaScript, чтобы не раздувать архив отладочными файлами.
При копировании метаданных в ./dist никогда не переноси туда файлы .env, локальный .npmrc с токеном NODE_AUTH_TOKEN или конфиги CI/CD. Если твой пакет поставляет консольные команды через секцию bin, убедись, что пути к ним в dist/package.json также скорректированы относительно ./dist.
Защита от мышечной памяти и проверка архива через npm pack
Даже с готовым скриптом остается риск привычки: если по инерции набрать npm publish из корня проекта, утилита выполнит сборку, но отправит в реестр весь корневой каталог вместо ./dist. Чтобы застраховаться от этого, Брамус превращает хук "prepublishOnly" в предохранитель "if [ -z $PUBLISH ]; then echo 'ERROR: Use npm run pub' && exit 1; fi", а выгрузку выносит в команду "pub": "PUBLISH=true npm run build && npm publish ./dist --access public".
При случайном вызове npm publish переменная окружения $PUBLISH пуста (-z $PUBLISH), поэтому скрипт возвращает exit 1 и блокирует отправку. Зато npm run pub передает флаг PUBLISH=true, запускает сборку с postbuild.js и публикует только папку ./dist. В командных пайплайнах такой подход дополняет изолированную отправку артефактов, разобранную в руководстве про безопасный выпуск npm-пакетов и защиту цепочки поставок.
Перед первой отправкой проверь состав архива в холостом режиме командой npm publish ./dist --dry-run или через npm pack ./dist --dry-run. Утилита сформирует пакет без загрузки в сеть и выведет список Tarball Contents: для hic-pageflip (1.0.1) отчет показывает архив hic-pageflip-1.0.1.tgz весом 3.2 kB (9.1 kB после распаковки) из 5 файлов в самом корне — LICENSE (1.1kB), README.md (1.8kB), index.js (850B), package.json (1.2kB) и core/engine.js (4.2kB). Также можно выполнить npm pack ./dist и распаковать архив через tar -xzf my-package-1.0.0.tgz, чтобы лично убедиться в чистоте структуры.
Не переживай, если в твоих текущих библиотеках пути импорта пока содержат /dist — нет нужды бросать дела и перекраивать все старые репозитории за один вечер. Начни со следующего планового обновления любого небольшого пакета: добавь короткий скрипт подготовки манифеста, проверь список файлов через npm pack ./dist --dry-run и переходи на чистую публикацию, когда убедишься, что каждый модуль лежит на своем месте.




