92 lines
2.5 KiB
Plaintext
92 lines
2.5 KiB
Plaintext
---
|
|
title: "bunx"
|
|
description: "Run packages from npm"
|
|
---
|
|
|
|
import Bunx from "/snippets/cli/bunx.mdx";
|
|
|
|
<Note>`bunx` is an alias for `bun x`. The `bunx` CLI is auto-installed when you install `bun`.</Note>
|
|
|
|
Use `bunx` to auto-install and run packages from `npm`. It's Bun's equivalent of `npx` or `yarn dlx`.
|
|
|
|
```bash terminal icon="terminal"
|
|
bunx cowsay "Hello world!"
|
|
```
|
|
|
|
<Note>
|
|
⚡️ **Speed** — With Bun's fast startup times, `bunx` is [roughly 100x
|
|
faster](https://twitter.com/jarredsumner/status/1606163655527059458) than `npx` for locally installed packages.
|
|
</Note>
|
|
|
|
Packages can declare executables in the `"bin"` field of their `package.json`. These are known as _package executables_ or _package binaries_.
|
|
|
|
```json package.json icon="file-json"
|
|
{
|
|
// ... other fields
|
|
"name": "my-cli",
|
|
"bin": {
|
|
"my-cli": "dist/index.js"
|
|
}
|
|
}
|
|
```
|
|
|
|
These executables are commonly plain JavaScript files marked with a [shebang line](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) naming the program that should run them. The following file runs with `node`.
|
|
|
|
```js dist/index.js icon="/icons/javascript.svg"
|
|
#!/usr/bin/env node
|
|
|
|
console.log("Hello world!");
|
|
```
|
|
|
|
Run these executables with `bunx`:
|
|
|
|
```bash terminal icon="terminal"
|
|
bunx my-cli
|
|
```
|
|
|
|
As with `npx`, `bunx` checks for a locally installed package first, then falls back to auto-installing it from `npm`. `bunx` stores installed packages in Bun's [global cache](/pm/global-cache) for future use.
|
|
|
|
## Arguments and flags
|
|
|
|
To pass additional command-line flags and arguments through to the executable, place them after the executable name.
|
|
|
|
```bash terminal icon="terminal"
|
|
bunx my-cli --foo bar
|
|
```
|
|
|
|
---
|
|
|
|
## Shebangs
|
|
|
|
By default, Bun respects shebangs. If an executable is marked with `#!/usr/bin/env node`, Bun spins up a `node` process to execute the file. To run the executable with Bun's runtime instead, pass the `--bun` flag.
|
|
|
|
```bash terminal icon="terminal"
|
|
bunx --bun my-cli
|
|
```
|
|
|
|
The `--bun` flag must occur _before_ the executable name. `bunx` passes flags that appear _after_ the name through to the executable.
|
|
|
|
```bash terminal icon="terminal"
|
|
bunx --bun my-cli # good
|
|
bunx my-cli --bun # bad
|
|
```
|
|
|
|
## Package flag
|
|
|
|
**`--package <pkg>` or `-p <pkg>`** - Run a binary from a specific package. Useful when the binary name differs from the package name:
|
|
|
|
```bash terminal icon="terminal"
|
|
bunx -p renovate renovate-config-validator
|
|
bunx --package @angular/cli ng
|
|
```
|
|
|
|
To force a script to always run with Bun, give it a `bun` shebang.
|
|
|
|
```js dist/index.js icon="/icons/javascript.svg"
|
|
#!/usr/bin/env bun
|
|
```
|
|
|
|
---
|
|
|
|
<Bunx />
|