`bun run`

The bun CLI can be used to execute JavaScript/TypeScript files, package.json scripts, and executable packages.

Performance

Bun is designed to start fast and run fast.

Under the hood Bun uses the JavaScriptCore engine, which is developed by Apple for Safari. In most cases, the startup and running performance is faster than V8, the engine used by Node.js and Chromium-based browsers. Its transpiler and runtime are written in Zig, a modern, high-performance language. On Linux, this translates into startup times 4x faster than Node.js.

Running a simple Hello World script on Linux

Run a file

备注

Compare to node <file>

Use bun run to execute a source file.

$ bun run index.js

Bun supports TypeScript and JSX out of the box. Every file is transpiled on the fly by Bun's fast native transpiler before being executed.

$ bun run index.js
$ bun run index.jsx
$ bun run index.ts
$ bun run index.tsx

Alternatively, you can omit the run keyword and use the "naked" command; it behaves identically.

$ bun index.tsx
$ bun index.js

--watch

To run a file in watch mode, use the --watch flag.

$ bun --watch run index.tsx

备注

Note — When using bun run, put Bun flags like --watch immediately after bun.

$ bun --watch run dev # ✔️ do this
$ bun run dev --watch # ❌ don't do this

Flags that occur at the end of the command will be ignored and passed through to the "dev" script itself.

Run a package.json script

$ bun [bun flags] run <script> [script flags]

Your package.json can define a number of named "scripts" that correspond to shell commands.

{
  // ... other fields
  "scripts": {
    "clean": "rm -rf dist && echo 'Done.'",
    "dev": "bun server.ts"
  }
}

Use bun run <script> to execute these scripts.

$ bun run clean
 $ rm -rf dist && echo 'Done.'
 Cleaning...
 Done.

Bun executes the script command in a subshell. It checks for the following shells in order, using the first one it finds: bash, sh, zsh.

备注

⚡️ The startup time for npm run on Linux is roughly 170ms; with Bun it is 6ms.

If there is a name conflict between a package.json script and a built-in bun command (install, dev, upgrade, etc.) Bun's built-in command takes precedence. In this case, use the more explicit bun run command to execute your package script.

$ bun run dev

To see a list of available scripts, run bun run without any arguments.

$ bun run
quickstart scripts:

 bun run clean
   rm -rf dist && echo 'Done.'

 bun run dev
   bun server.ts

2 scripts

Bun respects lifecycle hooks. For instance, bun run clean will execute preclean and postclean, if defined. If the pre<script> fails, Bun will not execute 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.

#!/usr/bin/env node

// do stuff

By default, Bun respects this shebang and executes the script with node. However, you can override this behavior with the --bun flag. For Node.js-based CLIs, this will run the CLI with Bun instead of Node.js.

$ bun run --bun vite

Filtering

in monorepos containing multiple packages, you can use the --filter argument to execute scripts in many packages at once.

Use bun run --filter <name_pattern> <script> to execute <script> in all packages whose name matches <name_pattern>. For example, if you have subdirectories containing packages named foo, bar and baz, running

bun run --filter 'ba*' <script>

will execute <script> in both bar and baz, but not in foo.

Find more details in the docs page for filter.

bun run - to pipe code from stdin

bun run - lets you read JavaScript, TypeScript, TSX, or JSX from stdin and execute it without writing to a temporary file first.

$ echo "console.log('Hello')" | bun run -
Hello

You can also use bun run - to redirect files into Bun. For example, to run a .js file as if it were a .ts file:

$ echo "console.log!('This is TypeScript!' as any)" > secretly-typescript.js
$ bun run - < secretly-typescript.js
This is TypeScript!

For convenience, all code is treated as TypeScript with JSX support when using bun run -.

bun run --smol

In memory-constrained environments, use the --smol flag to reduce memory usage at a cost to performance.

$ bun --smol run index.tsx

This causes the garbage collector to run more frequently, which can slow down execution. However, it can be useful in environments with limited memory. Bun automatically 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, so this is mostly useful for cases where you want to make the heap size grow more slowly.