The benchmark runs a Hello World script on Linux.
Run a file
Usebun run to execute a source file.
terminal
terminal
run keyword and use the “naked” command; it behaves identically.
terminal
--watch
To run a file in watch mode, use the --watch flag.
terminal
When using
bun run, put Bun flags like --watch immediately after bun.bun ignores flags at the end of the command and passes them through to the "dev" script itself.Run a package.json script
Compare to
npm run <script> or yarn <script>package.json can define named "scripts" that correspond to shell commands.
package.json
bun run <script> to execute these scripts.
terminal
bash, sh, zsh. On Windows, it uses the Bun Shell to support bash-like syntax and many common commands.
⚡️ The startup time for
npm run on Linux is roughly 170ms; with Bun it is 6ms.bun <script>. If a built-in bun command has the same name, the built-in command takes precedence; use the explicit bun run <script> to run your package script instead.
terminal
bun run without any arguments.
terminal
bun run clean runs preclean and postclean, if defined. If the pre<script> fails, Bun does not run the script itself.
--bun
It’s common for package.json scripts to reference locally-installed CLIs like vite or next. These CLIs are often JavaScript files marked with a shebang to indicate that they should be executed with node.
cli.js
node. The --bun flag overrides it: the CLI runs with Bun instead of Node.js.
terminal
Filtering
In a monorepo, the--filter argument runs a script in many packages at once.
bun run --filter <pattern> <script> executes <script> in every package selected by <pattern>. The pattern can be a package name glob, a ./path, a {dir} directory or a dependency relation like foo....
For example, if you have subdirectories containing packages named foo, bar and baz, running
terminal
<script> in both bar and baz, but not in foo.
See --filter.
bun run - to pipe code from stdin
bun run - reads JavaScript, TypeScript, TSX, or JSX from stdin and executes it without writing to a temporary file first.
terminal
bun run - to redirect files into Bun. For example, to run a .js file as if it were a .ts file:
terminal
bun run - treats all input as TypeScript with JSX support.
bun run --console-depth
Control the depth of object inspection in console output with the --console-depth flag.
terminal
--console-depth sets how deeply Bun displays nested objects in console.log() output. The default depth is 2. Higher values show more nested properties but may produce verbose output for complex objects.
console.ts
bun run --smol
In memory-constrained environments, use the --smol flag to reduce memory usage at a cost to performance.
terminal
--smol makes the garbage collector run more frequently, which can slow down execution. Bun adjusts the garbage collector’s heap size based on the available memory (accounting for cgroups and other memory limits) with and without the --smol flag. The flag is therefore mostly useful when you want the heap to grow more slowly.
Resolution order
Bun always executes absolute paths and paths starting with./ or .\\ as source files. Unless you use bun run, a name with an allowed extension resolves to the file rather than a package.json script.
When a package.json script and a file have the same name, bun run prefers the script. The full resolution order is:
package.jsonscripts:bun run build- Source files:
bun run src/main.js - Binaries from project packages:
bun add eslint && bun run eslint - (
bun runonly) System commands:bun run ls
CLI Usage
General Execution Options
Workspace Management
Number of lines of script output shown when using —filter (default: 10). Set to 0 to show all lines
Runtime & Process Control
Force a script or package to use Bun’s runtime instead of Node.js (via symlinking node). Alias:
-bOpen the Node.js-compatible REPL (
node:repl). When combined with -e, starts the REPL and
then evaluates the script. Under —interactive, -e is raw JavaScript (matching
node -i -e). Use bun repl for TypeScript. Distinct from bun repl, which is
Bun’s native REPL.Development Workflow
Debugging
Dependency & Module Resolution
Configure auto-install behavior. One of
auto (default, auto-installs when no node_modules),
fallback (missing packages only), force (always)Transpilation & Language Features
Substitute K:V while parsing, e.g.
—define process.env.NODE_ENV:“development”. Bun parses values as
JSON. Alias: -dParse files with
.ext:loader, e.g. —loader .js:jsx. Valid loaders: js,
jsx, ts, tsx, json, toml, text,
file, wasm, napi. Alias: -lDeclares the module specifier used to import the jsx and jsxs factory functions. Default:
reactNetworking & Security
Set the default order of DNS lookup results. Valid orders:
verbatim (default), ipv4first,
ipv6first