Что такое bunx и когда его использовать

bunx — это менеджер запуска пакетов от Bun, псевдоним для bun x. Он загружает и запускает бинарный файл пакета из npm без глобальной установки — ту же задачу, что выполняют npx и yarn dlx.

Если вы когда-нибудь ждали, пока npx запустит команду для создания проекта, которую вы выполняете десятки раз в день, именно эту задержку и призван устранить bunx. Если вы ежедневно набираете npx create-next-app или npx shadcn@latest, то bunx — это практически полноценная замена, доступная сразу после установки Bun. Однако перед переходом стоит разобраться в одном нюансе среды выполнения (флаг --bun) и одном реальном подводном камне (инструменты, жёстко прописывающие строку npx).

В этой статье рассматривается концептуальная модель: что такое bunx, как он разрешает пакеты, почему запускается быстрее npx, что на самом деле делает флаг --bun и когда стоит его использовать.

Что такое bunx?

bunx запускает исполняемый файл из npm-пакета без глобальной установки и поставляется вместе с Bun автоматически. В документации подтверждается, что bunx является псевдонимом для bun x и устанавливается автоматически при установке bun. Это аналог npx или yarn dlx в экосистеме Bun.

Синтаксис вызова идентичен npx:

# npx
npx create-next-app@latest my-app

# bunx
bunx create-next-app@latest my-app

Пакеты объявляют свои бинарные файлы в поле "bin" файла package.json; команда bunx <package> находит этот бинарный файл и запускает его. Фиксация версии работает так же, как в npx: достаточно добавить @version к имени пакета:

bunx uglify-js@3.14.0 app.js
bunx shadcn@latest add button

Если имя бинарного файла отличается от имени пакета, используйте флаг -p/--package, чтобы явно указать пакет, а затем имя исполняемого файла:

bunx -p @angular/cli ng new my-app

Как bunx разрешает пакеты?

bunx сначала проверяет наличие локально установленной копии пакета, затем при необходимости автоматически устанавливает его из npm и сохраняет в глобальном кэше Bun для повторного использования. Это задокументированное поведение: «Как и npx, bunx сначала проверяет наличие локально установленного пакета, а затем при необходимости автоматически устанавливает его из npm». Разрешённые пакеты попадают в глобальный кэш Bun, поэтому при последующих запусках загрузка не требуется.

Важное уточнение: современный npx (npm v7+, то есть npm exec) не загружает пакет заново при каждом запуске. Он также использует постоянный пользовательский кэш и повторно применяет пакеты при повторных вызовах. Таким образом, реальное отличие состоит не в том, что «npx не сохраняет, а bunx сохраняет» — оба инструмента кэшируют пакеты. Принципиальная разница — в расположении кэша (собственное глобальное хранилище Bun) и накладных расходах среды выполнения при переходе от вызова к исполнению.

Почему bunx быстрее npx

bunx запускается быстрее, поскольку работает на среде выполнения Bun, построенной на JavaScriptCore (движок браузера Safari), а не запускает Node, что снижает фиксированные затраты на старт менеджера запуска пакетов. Команда Bun конкретизирует это преимущество: при представлении bunx утверждалось, что он устанавливает и запускает исполняемые файлы из npm в 100 раз быстрее, чем npx, — эта цифра в документации относится именно к локально установленным пакетам.

Воспринимайте это число как заявленный показатель Bun для случая «тёплого» запуска с уже установленным пакетом, а не как универсальный бенчмарк. Преимущество в скорости запуска — это то, что актуально в общем случае: при «холодном» вызове CLI-инструмента (который вы выполняете десятки раз в день при создании проектов) именно меньшие накладные расходы Bun на запуск процесса позволяют сэкономить время. При первой установке, требующей обращения к сети, оба инструмента несут одинаковые затраты на загрузку, и разница в скорости сводится к пропускной способности установки плюс дельта запуска, а не к разрыву в 100 раз.

Если вам нужна цифра, которой вы можете доверять, измерьте самостоятельно, разделив «холодный» и «тёплый» запуск кэша:

# тёплый кэш (оба уже разрешены) vs холодный — измеряйте, не предполагайте
hyperfine 'npx cowsay hi' 'bunx cowsay hi'

Флаг —bun

Флаг --bun принудительно запускает CLI-инструмент (например, Vite, Next или Prisma) в среде выполнения Bun вместо Node, переопределяя шебанг #!/usr/bin/env node, с которым поставляется инструмент. По умолчанию Bun соблюдает этот шебанг и запускает node-процесс для выполнения файла; флаг --bun указывает использовать вместо этого среду выполнения Bun:

bunx --bun vite dev

Флаг чувствителен к позиции. Он должен стоять перед именем исполняемого файла. Всё, что указано после имени, передаётся непосредственно инструменту в качестве его собственных аргументов:

bunx --bun my-cli   # правильно — запускает my-cli на Bun
bunx my-cli --bun   # неправильно — передаёт --bun в my-cli

Используйте --bun, когда вам действительно нужно, чтобы инструмент работал на Bun — для использования более быстрого запуска или встроенной поддержки TypeScript. Оставьте флаг отключённым (по умолчанию), когда инструмент зависит от специфического поведения Node: некоторые инструменты сборки и CLI предполагают использование внутренних механизмов Node, и принудительный перевод на среду выполнения Bun может вызвать проблемы совместимости. На практике распространённая ошибка выглядит так: CLI работает при обычном bunx toolname, но падает после добавления --bun, меняющего среду выполнения. Решение, как правило, — убрать --bun и позволить шебангу Node работать штатно.

Когда использовать bunx (и когда оставаться на npx)

Правило выбора: используйте bunx для разовых задач по созданию проектов и запуска CLI-инструментов (bunx create-next-app my-app, bunx prisma migrate, bunx prettier foo.js) и оставайтесь на npx только тогда, когда инструмент жёстко прописывает строку npx или не работает в среде выполнения Bun.

Единственный реальный подводный камень — инструменты, вызывающие npx по имени. Псевдоним оболочки вида alias npx=bunx работает при интерактивном вводе команд, однако псевдонимы оболочки существуют только в интерактивных сессиях: они невидимы для неинтерактивных процессов. Инструмент, который вызывает npx внутри себя (например, uv run, обращающийся к нему внутренне), вообще не увидит этот псевдоним.

Решение — поместить настоящий исполняемый файл с именем npx в PATH, чтобы любой процесс, запускающий npx, разрешал его в ваш шим. Способ, описанный в htdocs, занимает три строки:

mkdir -p ~/.local/bin
printf '#!/bin/sh\nexec bunx "$@"\n' > ~/.local/bin/npx
chmod +x ~/.local/bin/npx

Убедитесь, что ~/.local/bin стоит в начале вашего PATH. Поскольку это реальный файл на диске, а не псевдоним оболочки, неинтерактивные процессы также его найдут. Если вам нужен запасной вариант, который перенаправляет через Bun только при его наличии, более сложный вариант с условной функцией-обёрткой и флагом --real для обхода, описанный nrjdalal, является расширенной версией той же идеи.

Заключение

Воспринимайте bunx как npx на более быстрой среде выполнения: тот же порядок разрешения, тот же синтаксис фиксации версий, та же форма команды — при меньших накладных расходах на запуск и пакетах, кэшированных в собственном хранилище Bun. Добавляйте флаг --bun только тогда, когда хотите, чтобы сам инструмент работал на Bun, ставьте его перед именем исполняемого файла и разместите настоящий шим npx в PATH для тех немногих инструментов, которым требуется именно эта команда. Установите Bun, замените один npx на bunx при следующем создании проекта и измерьте разницу самостоятельно.

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

Является ли bunx полноценной заменой npx?

bunx является практически полноценной заменой npx: у них одинаковая форма команды, одинаковый синтаксис фиксации версий с суффиксом @version и одинаковый порядок разрешения с приоритетом локальных пакетов. Исключение составляют инструменты или скрипты, которые внутренне вызывают строку npx: они не распознают bunx, если только не поместить настоящий исполняемый файл с именем npx в PATH. В таких случаях bunx не подставляется автоматически.

Работает ли bunx без отдельной установки Bun?

Нет, bunx требует наличия Bun. bunx является псевдонимом команды bun x и устанавливается автоматически при установке самого Bun, поэтому отдельного пакета bunx не существует. После установки Bun команда bunx доступна без дополнительной настройки. Если Bun не установлен, команда bunx не существует, и необходимо использовать npx или другой менеджер запуска пакетов.

В чём разница между bun x и bunx?

Функциональной разницы нет: bunx — это просто псевдоним для bun x, поэтому обе команды работают идентично. Обе вызывают менеджер запуска пакетов Bun для выполнения бинарного файла пакета без глобальной установки. Используйте тот вариант написания, который вам удобнее. bunx существует главным образом как более короткая форма, знакомая разработчикам, пришедшим из экосистемы npm.

Почему bunx --bun ломает некоторые CLI, которые нормально работают без этого флага?

Потому что --bun принудительно переводит CLI на среду выполнения Bun вместо Node, переопределяя шебанг Node, с которым поставляется инструмент. Некоторые инструменты сборки и CLI зависят от внутренних механизмов Node, поэтому смена среды выполнения приводит к проблемам совместимости. Инструмент, работающий при обычном bunx toolname, может упасть после добавления --bun. Решение — убрать --bun и позволить инструменту работать на Node в соответствии с его шебангом.