diff --git a/docs/cli/run.md b/docs/cli/run.md index d8aa5617ff..80a00b2f93 100644 --- a/docs/cli/run.md +++ b/docs/cli/run.md @@ -223,25 +223,4 @@ When there is a package.json script and a file with the same name, `bun run` pri 3. Binaries from project packages, eg `bun add eslint && bun run eslint` 4. (`bun run` only) System commands, eg `bun run ls` -## `.bunx` files on Windows - -To make `bun run` even faster on Windows, we engineered a new file format: `.bunx`. - -The `.bunx` file is a cross-filesystem symlink that is able to start scripts or executables using Bun or Node.js. We decided to create this for several reasons: - -- Symlinks are not guaranteed to work on Windows. -- Shebangs at the top of a file (`#!/usr/bin/env bun`) are not read on Windows. -- We want to avoid creating three permutations of each executable: `.cmd`, `.sh`, and `.ps1`. -- We want to avoid confusing "Terminate batch job? (Y/n)" prompts. - -The end result is that `bun run` is 11x faster than `npm run`, and `bunx` is also 11x faster than `npx`. - -{% image src="/images/bun-run-on-windows.png" caption="Time spent running `bunx cowsay` vs `npx cowsay` on Windows." /%} - -Even if you only use Bun as a package manager and not a runtime, `.bunx` just works with Node.js. This also solves the annoying "Terminate batch job?" prompt that Windows developers are used to when sending ctrl-c to a running script. - -{% image src="/images/terminate-batch-job-bun.gif" /%} - -{% image src="/images/terminate-batch-job-npm.gif" /%} - {% bunCLIUsage command="run" /%} diff --git a/docs/install/index.md b/docs/install/index.md index cb1b83aa5f..28acfd557d 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -202,9 +202,9 @@ To remove a dependency: $ bun remove preact ``` -## Package executables +## Package executables and bin linking -When packages define executables in their `"bin"` field, Bun automatically creates links to these executables in `node_modules/.bin`. This allows you to run them with `bun run`, `bunx`, or directly from `package.json` scripts. +When you install packages that define executables in their `"bin"` field, Bun automatically creates links to these executables in `node_modules/.bin`. This makes them available for execution via `bun run`, `bunx`, or directly in `package.json` scripts. ```json { @@ -215,16 +215,68 @@ When packages define executables in their `"bin"` field, Bun automatically creat } ``` -### `.bunx` files on Windows +After running `bun install`, you can execute these binaries in several ways: -On Windows, Bun uses a special `.bunx` file format for package executables instead of traditional symlinks. This provides several benefits: +```bash +# Via bun run +$ bun run my-cli -- **Cross-filesystem compatibility** - Works reliably across different Windows filesystems where symlinks may not be supported -- **No shebang limitations** - Windows doesn't read shebangs (`#!/usr/bin/env node`), but `.bunx` files handle this automatically -- **Simplified execution** - Avoids creating multiple wrapper files (`.cmd`, `.sh`, `.ps1`) for each executable -- **Better developer experience** - Eliminates the annoying "Terminate batch job? (Y/n)" prompts when stopping scripts +# Via bunx +$ bunx my-cli -The `.bunx` format allows executables to work seamlessly with both Bun and Node.js, making it ideal even if you're only using Bun as a package manager. +# In package.json scripts +{ + "scripts": { + "build": "my-cli --build" + } +} +``` + +### How bin linking works on Windows with `.bunx` files + +On Windows, `bun install` uses a special `.bunx` file format when creating executable links instead of traditional symlinks. This innovative approach solves several Windows-specific challenges: + +#### Why `.bunx` files? + +Traditional package managers struggle with executables on Windows, often creating multiple wrapper files (`.cmd`, `.sh`, `.ps1`) for each binary. Bun's `.bunx` format was engineered to address these issues: + +- **Symlinks are not guaranteed to work on Windows** - Different filesystems and permission levels can prevent symlink creation +- **Shebangs (`#!/usr/bin/env node`) are not read on Windows** - Windows doesn't natively support Unix-style shebangs +- **Multiple wrapper files cause confusion** - Having `.cmd`, `.sh`, and `.ps1` versions of each executable clutters `node_modules/.bin` +- **Poor developer experience** - The infamous "Terminate batch job? (Y/n)" prompt interrupts workflow when stopping scripts + +#### How `.bunx` files work + +The `.bunx` file is a cross-filesystem symlink that can start scripts or executables using either Bun or Node.js. When `bun install` processes a package with binaries: + +1. Instead of creating traditional symlinks or wrapper scripts, it creates a single `.bunx` file +2. This file acts as a universal executable that works across different Windows configurations +3. The file correctly handles both Bun and Node.js execution contexts +4. No additional wrapper files are needed + +#### Performance benefits + +The `.bunx` format delivers significant performance improvements: + +- `bun run` is **11x faster** than `npm run` on Windows +- `bunx` is **11x faster** than `npx` for executing package binaries +- Startup time is dramatically reduced by avoiding batch file indirection + +{% image src="/images/bun-run-on-windows.png" caption="Time spent running `bunx cowsay` vs `npx cowsay` on Windows." /%} + +#### Better developer experience + +Beyond performance, `.bunx` files improve the development workflow: + +- **No more "Terminate batch job?" prompts** - Clean interruption when pressing Ctrl+C +- **Works with both Bun and Node.js** - Even if you only use Bun as a package manager, executables work correctly with Node.js +- **Simplified debugging** - Single file format makes it easier to understand what's being executed + +{% image src="/images/terminate-batch-job-bun.gif" /%} + +{% image src="/images/terminate-batch-job-npm.gif" /%} + +The `.bunx` format is automatically used when you run `bun install` on Windows - no configuration needed. It's part of Bun's commitment to making JavaScript development faster and more enjoyable on every platform. ## Git dependencies