Управление зависимостями

Deno — это полноценный менеджер пакетов для пакетов npm и JSR, встроенный в двоичный файл deno. Он работает с deno.json, package.json или с обоими одновременно и безопасен по умолчанию: сценарии жизненного цикла npm не запускаются, пока вы не разрешите их выполнение. На этой странице описан повседневный рабочий процесс; в таблице команд перечислены все команды.

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

В проекте, в котором уже объявлены зависимости (в package.json или deno.json), установите их командой:

deno install

Добавьте новую зависимость из npm или JSR. Имена без префикса обозначают пакеты npm, например npm install:

deno install express            # any npm package
deno install jsr:@std/assert    # a JSR package

Зависимость будет записана в файл конфигурации проекта, а импортировать её можно будет по краткому имени:

import express from "express";
import { assertEquals } from "@std/assert";

Набор команд для работы с зависимостями

Для каждой задачи, связанной с зависимостями, предусмотрена встроенная подкоманда. По ссылкам можно перейти к полному описанию каждой команды:

Выбор версий

Можно задать диапазон версий импортируемого пакета. Для этого используется символ @, за которым следует спецификатор диапазона версий, соответствующий схеме версионирования semver. Если нужно использовать один диапазон версий в нескольких участниках рабочей области, см. раздел catalog: о централизованном управлении версиями зависимостей.

Например:

@scopename/mypackage           # highest version
@scopename/mypackage@16.1.0    # exact version
@scopename/mypackage@16        # highest 16.x version >= 16.0.0
@scopename/mypackage@^16.1.0   # highest 16.x version >= 16.1.0
@scopename/mypackage@~16.1.0   # highest 16.1.x version >= 16.1.0

Ниже перечислены все способы указать версию или диапазон версий:

Просмотр и обновление зависимостей

Узнайте, для каких зависимостей доступны более новые версии, а затем обновите их:

deno outdated      # display what's behind, without changing anything
deno update        # update to the latest semver-compatible versions
deno update --latest   # ignore semver ranges and go to the newest releases

Чтобы узнать, откуда взялся пакет, команда deno why выведет все пути зависимостей, ведущие к нему:

deno why npm:kleur

Команда deno info показывает полный граф зависимостей модуля, в том числе размеры и расположение кэша, для точки входа или любого спецификатора:

deno info main.ts
deno info jsr:@std/http

Проверка на наличие уязвимостей

Команда deno audit проверяет установленные зависимости по базам данных уязвимостей:

deno audit                 # report known vulnerabilities
deno audit --level=high    # only high and critical severity
deno audit --fix           # upgrade affected packages automatically
deno audit --socket        # check against the socket.dev database

Аудит — одна из мер, которая помогает со временем поддерживать безопасность дерева зависимостей. О других практиках см. раздел Управление цепочкой поставок: минимальный возраст зависимостей, работа с lock-файлом и рекомендуемая базовая настройка CI.

Сценарии жизненного цикла

В отличие от npm, Deno по умолчанию не запускает сценарии preinstall/postinstall: сценарии установки пакета представляют собой распространённый вектор атак, поэтому их выполнение нужно разрешать отдельно. Если зависимость действительно нуждается в таких сценариях (например, для нативных дополнений), разрешите их явно:

deno install --allow-scripts=npm:better-sqlite3

Также можно управлять разрешениями в интерактивном режиме с помощью команды deno approve-scripts. Сценарии выполняются только при использовании каталога node_modules.

Lock-файл и воспроизводимые установки

Deno автоматически поддерживает файл deno.lock, в котором записаны точная версия и хеш целостности каждой зависимости, и проверяет его при последующих запусках. Добавьте его в систему контроля версий. В CI и production выполняйте строгую установку из lock-файла с помощью команды deno ci. Она завершится с ошибкой, если deno.lock отсутствует или устарел, вместо того чтобы молча разрешать новые версии:

deno ci          # like npm ci
deno ci --prod   # additionally skip devDependencies

Также можно принудительно использовать неизменяемый lock-файл в любой команде с помощью --frozen или настроить поведение и путь к lock-файлу в deno.json. О важности lock-файла и способах решения проблем с ним см. раздел Управление цепочкой поставок.

node_modules и кэш

По умолчанию Deno хранит зависимости в глобальном кэше и создаёт локальный каталог node_modules, только если в проекте есть package.json. Настройте это с помощью параметра nodeModulesDir в deno.json.

По умолчанию Deno использует глобальный каталог кэша (DENO_DIR) для загруженных зависимостей. Этот кэш общий для всех проектов.

Чтобы заставить deno повторно загрузить и скомпилировать модули в кэш, используйте флаг --reload.

# Reload everything
deno run --reload my_module.ts

# Reload a specific module
deno run --reload=jsr:@std/fs my_module.ts

Действует и обратное: --cached-only полностью запрещает доступ к сети и завершает работу с ошибкой, если чего-либо из дерева зависимостей ещё нет в кэше. Это удобно для работы без подключения к сети и воспроизводимых сборок CI:

deno run --cached-only mod.ts

Локальное хранение удалённых модулей

Если в проекте есть внешние зависимости, их можно хранить локально, чтобы не загружать из интернета при каждой сборке проекта. Это особенно полезно при сборке проекта на сервере CI или в контейнере Docker, а также при исправлении или изменении удалённых зависимостей.

Deno предоставляет эту возможность с помощью настройки в файле deno.json:

{
  "vendor": true
}

Добавьте приведённый выше фрагмент в файл deno.json, и при запуске проекта Deno будет кэшировать все зависимости локально в каталоге vendor. Также можно сразу кэшировать зависимости с помощью команды deno install --entrypoint:

deno install --entrypoint main.ts

Затем запустите приложение как обычно с помощью deno run:

deno run main.ts

После сохранения зависимостей локально можно запускать main.ts без доступа к интернету, используя флаг --cached-only, который заставляет Deno использовать только доступные локально модули.

Дополнительные способы переопределения, например подмена зависимостей во время разработки, описаны в разделе Переопределение зависимостей.

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

Deno предоставляет механизмы переопределения зависимостей, позволяющие разработчикам использовать собственные или локальные версии библиотек во время разработки и тестирования.

Примечание. Если нужно кэшировать и изменять зависимости локально для использования в разных сборках, рассмотрите возможность локального хранения удалённых модулей.

Переопределение локальных пакетов

Для разработчиков, знакомых с npm link в Node.js, в Deno предусмотрена аналогичная возможность для локальных пакетов JSR и npm. Она настраивается с помощью поля links в deno.json. Это позволяет переопределять зависимости локальными версиями во время разработки, не публикуя их.

Пример:

{
  "links": [
    "../some-package-or-workspace"
  ]
}

Основные моменты:

• Поле links принимает пути к каталогам с пакетами или рабочими областями. Если указать отдельный пакет в рабочей области, будет включена вся рабочая область.
• Поддерживаются пакеты JSR и npm.
• Эта возможность учитывается только в корне рабочей области. Использование links в другом месте приведёт к появлению предупреждений.

Ограничения:

• Переопределение зависимостей на основе Git недоступно.
• Поле links необходимо правильно настроить в корне рабочей области.

Переопределение пакетов npm

Deno поддерживает связывание пакетов npm с локальными версиями, подобно связыванию пакетов JSR. Это позволяет использовать локальную копию пакета npm во время разработки, не публикуя её.

Чтобы использовать локальный пакет npm, настройте поле links в файле deno.json:

{
  "links": [
    "../path/to/local_npm_package"
  ]
}

Для этой возможности требуется каталог node_modules; её поведение зависит от настройки nodeModulesDir:

• При использовании "nodeModulesDir": "auto" каталог создаётся заново при каждом запуске. Это немного увеличивает время запуска, но гарантирует, что всегда будет использоваться последняя версия.
• При использовании "nodeModulesDir": "manual" (по умолчанию при работе с package.json) после обновления пакета нужно выполнить deno install, чтобы изменения попали в каталог node_modules рабочей области.

Ограничения:

• Указание локальной копии пакета npm или изменение его зависимостей приведёт к удалению пакетов npm из lock-файла, что может изменить разрешение зависимостей npm.
• Имя пакета npm должно существовать в реестре, даже если используется локальная копия.

Переопределение HTTPS-импортов

Deno также позволяет переопределять HTTPS-импорты с помощью поля scopes в deno.json. Эта возможность особенно полезна, когда для отладки или временного исправления нужно заменить удалённую зависимость локальной версией с изменениями.

Пример:

{
  "imports": {
    "example/": "https://deno.land/x/example/"
  },
  "scopes": {
    "https://deno.land/x/example/": {
      "https://deno.land/x/my-library@1.0.0/mod.ts": "./patched/mod.ts"
    }
  }
}

Основные моменты:

• Поле scopes в карте импортов позволяет перенаправлять отдельные импорты на альтернативные пути.
• Обычно это используется для замены удалённых зависимостей локальными файлами при тестировании или разработке.
• Области действия применяются только к корню проекта. Вложенные области действия в зависимостях игнорируются.

Зависимости только для разработки

Иногда зависимости нужны только во время разработки, например зависимости тестовых файлов или инструменты сборки. В Deno среде выполнения не нужно разделять зависимости для разработки и production: среда выполнения загружает и устанавливает только те зависимости, которые действительно используются в исполняемом коде.

Однако пометка зависимостей для разработки может быть полезна читателям вашего пакета. При использовании deno.json принято добавлять комментарий // dev после каждой зависимости, используемой «только для разработки»:

{
  "imports": {
    "@std/fs": "jsr:@std/fs@1",
    "@std/testing": "jsr:@std/testing@1" // dev
  }
}

При использовании файла package.json зависимости для разработки можно добавить в отдельное поле devDependencies:

{
  "dependencies": {
    "pg": "npm:pg@^8.0.0"
  },
  "devDependencies": {
    "prettier": "^3"
  }
}

Если вы в основном работаете с package.json, задайте "preferPackageJson": true в deno.json, чтобы команды deno add, deno install и deno remove по умолчанию записывали данные туда, а не в deno.json, без необходимости каждый раз передавать --package-json. См. preferPackageJson.

Пакеты JSR в package.json

Можно напрямую добавлять зависимости JSR в package.json с помощью схемы jsr: без отдельного файла deno.json:

{
  "dependencies": {
    "@std/path": "jsr:^1.0.9"
  }
}

Это работает с deno install и позволяет добавлять пакеты JSR в любой проект, использующий package.json для управления зависимостями.

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

Поле overrides в package.json позволяет управлять версиями транзитивных зависимостей во всём дереве зависимостей. Это удобно для установки исправлений безопасности, устранения проблем совместимости версий или замены пакетов:

{
  "dependencies": {
    "express": "^4.18.0"
  },
  "overrides": {
    "cookie": "0.7.0",
    "express": {
      "qs": "6.13.0"
    }
  }
}

В этом примере для cookie глобально зафиксирована версия 0.7.0, а qs переопределяется только при необходимости для express.

Почему в Deno нет поля devImports?

Чтобы понять, почему Deno не выделяет зависимости для разработки в манифесте пакета, важно разобраться, какую задачу они решают.

При развёртывании приложения часто нужно устанавливать только те зависимости, которые действительно используются в исполняемом коде. Это помогает ускорить запуск и уменьшить размер развёрнутого приложения.

Исторически этого добивались, выделяя зависимости для разработки в отдельное поле devDependencies файла package.json. При развёртывании приложения devDependencies не устанавливаются — устанавливаются только зависимости.

На практике такой подход оказался проблематичным. Легко забыть перенести зависимость из dependencies в devDependencies, когда она из зависимости времени выполнения становится зависимостью для разработки. Кроме того, некоторые пакеты, которые по смыслу являются зависимостями «для разработки», например (@types/*), часто указываются в dependencies в файлах package.json. В результате они устанавливаются в production, хотя в этом нет необходимости.

Deno предлагает два способа устанавливать зависимости только для production:

• deno install --prod — исключает devDependencies из package.json. Также можно передать --skip-types, чтобы дополнительно исключить пакеты @types/*.
• deno install --entrypoint — устанавливает только зависимости, которые прямо или транзитивно импортируются указанным файлом точки входа. При использовании вместе с --prod зависимости, используемые только для типов, также исключаются из графа модулей.

Дополнительные сведения см. в справочнике по команде deno install.

HTTPS-импорты

Deno может импортировать модули напрямую по URL-адресам https: — как непосредственно в коде, так и через карту импортов deno.json. Это удобно для небольших скриптов в одном файле, но для приложений рекомендуются реестры (JSR, npm): HTTPS-импорты могут ссылаться на разные версии в разных файлах, не управляются с помощью deno add/deno install и требуют доверия к серверу, с которого загружаются. Чтобы зафиксировать их версии и хранить локально, см. раздел о локальном хранении зависимостей.

Дополнительные сведения

• Публикация пакетов: JSR, npm с помощью deno pack и выбор реестра.
• Управление цепочкой поставок: работа с lock-файлом, минимальный возраст зависимостей, процессы аудита и базовая настройка CI.
• Закрытые репозитории: аутентификация на удалённых хостах модулей с помощью DENO_AUTH_TOKENS. О закрытых реестрах npm см. раздел Поддержка npm.