Если в рабочем каталоге или выше не найден каталог node_modules, Bun откажется от разрешения модулей в стиле Node.js в пользу алгоритма разрешения модулей Bun.

При разрешении модулей в стиле Bun все импортируемые пакеты автоматически устанавливаются на лету в глобальный кэш модулей во время выполнения (тот же кэш, что используется bun install).

import { foo } from "foo"; // установить версию `latest`

foo();

При первом запуске этого скрипта Bun автоматически установит "foo" и закэширует его. При следующем запуске скрипта будет использована закэшированная версия.

---

Разрешение версий

Для определения версии для установки Bun следует следующему алгоритму:

1. Проверить наличие файла bun.lock в корне проекта. Если он существует, использовать версию, указанную в файле блокировки.
2. В противном случае просканировать дерево вверх в поисках package.json, который включает "foo" как зависимость. Если найден, использовать указанную версию или диапазон версий semver.
3. В противном случае использовать latest.

---

Поведение кэша

После определения версии или диапазона версий Bun будет:

1. Проверять кэш модулей на наличие совместимой версии. Если она существует, использовать её.
2. При разрешении latest Bun проверит, был ли package@latest загружен и закэширован в последние 24 часа. Если да, использовать его.
3. В противном случае загрузить и установить соответствующую версию из реестра npm.

---

Установка

Пакеты устанавливаются и кэшируются в <cache>/<pkg>@<version>, поэтому несколько версий одного и того же пакета могут быть закэшированы одновременно. Кроме того, создаётся симлинка в <cache>/<pkg>/<version> для ускорения поиска всех версий пакета, существующих в кэше.

---

Спецификаторы версий

Весь этот алгоритм разрешения можно обойти, указав версию или диапазон версий непосредственно в операторе импорта.

import { z } from "zod@3.0.0"; // конкретная версия
import { z } from "zod@next"; // тег npm
import { z } from "zod@^3.20.0"; // диапазон semver

---

Преимущества

Такой подход к автоматической установке полезен по нескольким причинам:

• Эффективность пространства — Каждая версия зависимости существует только в одном месте на диске. Это огромная экономия пространства и времени по сравнению с избыточными установками на проект.
• Портативность — Для распространения простых скриптов и gist ваш исходный файл самодостаточен. Нет необходимости архивировать каталог, содержащий ваш код и файлы конфигурации. Со спецификаторами версий в операторах import даже package.json не требуется.
• Удобство — Нет необходимости запускать npm install или bun install перед запуском файла или скрипта. Просто bun run.
• Обратная совместимость — Поскольку Bun всё ещё уважает версии, указанные в package.json, если он существует, вы можете переключиться на разрешение в стиле Bun одной командой: rm -rf node_modules.

---

Ограничения

• Отсутствие Intellisense. Автодополнение TypeScript в IDE полагается на наличие файлов объявлений типов внутри node_modules. Мы исследуем различные решения этой проблемы.
• Отсутствие поддержки patch-package

---

Часто задаваемые вопросы

Чем это отличается от того, что делает pnpm?

С pnpm вы должны запустить pnpm install, который создаёт папку node_modules из симлинков для разрешения средой выполнения. В отличие от этого, Bun разрешает зависимости на лету при запуске файла; нет необходимости заранее запускать какую-либо команду install. Bun также не создаёт папку node_modules.

Чем это отличается от того, что делает Yarn Plug'N'Play?

С Yarn вы должны запустить yarn install перед запуском скрипта. В отличие от этого, Bun разрешает зависимости на лету при запуске файла; нет необходимости заранее запускать какую-либо команду install.

Yarn Plug'N'Play также использует zip-файлы для хранения зависимостей. Это делает загрузку зависимостей медленнее во время выполнения, так как случайные чтения zip-файлов обычно медленнее, чем эквивалентное чтение с диска.

Чем это отличается от того, что делает Deno?

Deno требует спецификатора npm: перед каждым npm import, не поддерживает карты импорта через compilerOptions.paths в tsconfig.json и имеет неполную поддержку настроек package.json. В отличие от Deno, Bun в настоящее время не поддерживает импорты по URL.