deno pack

Команда deno pack создаёт совместимый с npm tarball (.tgz) из проекта Deno, чтобы вы могли опубликовать библиотеку, написанную на Deno, непосредственно в реестре npm. Она транспилирует TypeScript в JavaScript, генерирует файлы объявлений .d.ts, переписывает спецификаторы импорта и формирует package.json, понятный потребителям, использующим только npm.

deno pack — это не аналог npm pack. Это этап сборки, который преобразует проект Deno/JSR в пакет, пригодный для публикации в npm, — примерно как deno transpile вместе с npm pack. Эта команда не читает существующий package.json, не учитывает .npmignore и не запускает скрипты жизненного цикла prepublishOnly / prepare.

Быстрый старт

deno pack

deno pack считывает метаданные пакета из deno.json (name, version и exports, которые используются для публикации в JSR) и записывает сжатый tarball в текущую директорию.

Для deno.json следующего вида:

{
  "name": "@scope/my-lib",
  "version": "1.0.0",
  "exports": "./mod.ts"
}

deno pack создаёт scope-my-lib-1.0.0.tgz (@ удаляется, а / становится - в соответствии с соглашением об именовании npm pack).

Содержимое tarball

Включаются только файлы, достижимые по графу модулей из exports. Ресурсы, отличные от JS, например файлы данных или WASM, включаются только в том случае, если на них есть импорты из JS/TS. Если нужно включить произвольные файлы, укажите их в качестве позиционных аргументов:

deno pack assets/icon.svg locales/*.json

Переписывание спецификаторов

Чтобы сгенерированный пакет работал в Node и у других потребителей npm, deno pack переписывает импорты во время транспиляции:

Поскольку импорты JSR преобразуются в спецификаторы @jsr/..., всем, кто устанавливает опубликованный tarball, нужно настроить реестр npm для JSR. Проще всего один раз запустить npx jsr add в проекте-потребителе; команда настроит записи .npmrc для области @jsr.

Подмена API Deno

Если в коде используется глобальный объект Deno.*, deno pack добавляет @deno/shim-deno как зависимость времени выполнения и внедряет подмену, чтобы пакет мог работать в Node.js. Подмена поддерживает подмножество Deno.*, которое можно напрямую сопоставить с API Node. Ознакомьтесь с документацией подмены, чтобы узнать, что именно полифилится.

Передайте --no-deno-shim, чтобы отключить эту возможность, например если вы уже предоставили собственную абстракцию или предполагаете запускать пакет только в Deno-on-npm.

Публикация в npm

deno pack
npm publish ./scope-my-lib-1.0.0.tgz

Типичный процесс выпуска версии:

# 1. Bump the version
deno bump-version patch

# 2. Build the tarball
deno pack

# 3. Verify the contents (extracted view)
tar -tzf scope-my-lib-1.0.0.tgz

# 4. Push to npm
npm publish ./scope-my-lib-1.0.0.tgz

Для выпуска версий в JSR используйте вместо этого deno publish — deno pack предназначена именно для реестра npm.

Поддержка рабочих пространств

В рабочем пространстве команда deno pack выполняется для участника, соответствующего текущей рабочей директории. Чтобы упаковать определённого участника из корневой директории:

cd packages/my-lib
deno pack

Межпространственные зависимости npm: / jsr: в сгенерированном package.json переписываются так, чтобы указывать на опубликованные версии, а не на других участников рабочего пространства. Перед публикацией tarball убедитесь, что эти зависимости выпущены отдельно.

Примеры

Переопределение версии

Полезно для разового выпуска предварительной версии без изменения deno.json:

deno pack --set-version 2.0.0-rc.1

Выбор пути вывода

deno pack --output dist/my-package.tgz

Предварительный просмотр без записи

deno pack --dry-run

--dry-run выводит список того, что попало бы в tarball, не создавая его. Это удобно в CI для проверки правил включения файлов.

Разрешить медленные типы

Медленные типы препятствуют генерации .d.ts. Передайте --allow-slow-types, чтобы всё равно создать пакет; tarball не будет содержать файлы объявлений.

deno pack --allow-slow-types

Не использовать подмену Deno

deno pack --no-deno-shim

Упаковка при изменениях в рабочей директории

deno pack --allow-dirty

По умолчанию deno pack отказывается создавать пакет, если в рабочем дереве Git есть незакоммиченные изменения, чтобы выпуски можно было воспроизвести по хешу коммита.

Исключение файлов

deno pack --ignore=tests/ --ignore='**/*.test.ts'

--ignore принимает шаблоны glob. Чтобы добавить несколько шаблонов, укажите несколько флагов --ignore.

Исключение карт исходного кода

deno pack --no-source-maps

По умолчанию карты исходного кода встраиваются в создаваемые файлы .js. Используйте --no-source-maps, чтобы удалить их: tarball станет меньше, но отлаживать код будет сложнее.

Ограничения

• Без записей bin. deno pack не формирует поле package.json bin. Публикация библиотек поддерживается; для CLI-инструментов, которым нужен исполняемый файл с шебангом node, по-прежнему требуется самостоятельно подготовить npm-пакет.
• Без нативных дополнений. Пакеты, связанные с нативным кодом или содержащие этап сборки node-gyp, не поддерживаются.
• Без .npmignore. Для исключения файлов используйте --ignore; .gitignore учитывается при определении того, что считается частью проекта.
• Без скриптов жизненного цикла. Хуки prepublishOnly / prepare / postinstall из написанного вручную package.json не запускаются, поскольку package.json генерируется, а не считывается.

Когда использовать deno pack, а когда — deno publish

Библиотеку можно опубликовать в обоих реестрах: выпустите версию в JSR с помощью deno publish, затем соберите и отправьте tarball в npm с помощью deno pack для пользователей, которые ещё не перешли на JSR.

См. также

• deno publish — выпуск версии в JSR
• deno transpile — этап генерации кода, который deno pack использует внутри
• deno bump-version — увеличение version в deno.json / package.json перед упаковкой
• Публикация модулей — обзор площадок, где можно публиковать библиотеки, написанные на Deno

deno pack [OPTIONS] [files]...