mirrors/bun.sh
1
0
Fork 0
mirror of https://github.com/oven-sh/bun synced 2026-02-09 18:38:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor: Move .bunx docs from bun run to bun install, expand coverage

Browse Source 
- Removed .bunx section from bun run docs (keep it focused on running scripts)
- Significantly expanded .bunx documentation in bun install docs
- Now properly explains how bin linking works during package installation
- Added detailed explanation of how .bunx files are created during install
- Better structured with subsections for clarity
- Emphasizes this is a package installation feature, not just runtime

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude Bot
2025-09-17 08:36:24 +00:00
parent 8adf0962e9
commit 49d502341c
2 changed files with 61 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/cli/run.md
View File

@@ -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" /%}

70
docs/install/index.md
View File

@@ -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