Bun Runtime | Bun Docs

File & Module System
Standards & Compatibility
Execute JavaScript/TypeScript files, package.json scripts, and executable packages with Bun's fast runtime.
The Bun Runtime is designed to start fast and run fast.
Bun uses the JavaScriptCore engine, developed by Apple for Safari. JavaScriptCore usually starts and runs faster than V8, the engine used by Node.js and Chromium-based browsers. Bun's transpiler and runtime are written in Rust. On Linux, Bun starts 4x faster than Node.js.
The benchmark runs a Hello World script on Linux.
Use bun run to execute a source file.
Bun supports TypeScript and JSX with no configuration. Bun transpiles every file on the fly with its native transpiler before running it.
Alternatively, you can omit the run keyword and use the "naked" command; it behaves identically.
To run a file in watch mode, use the --watch flag.
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.
Bun runs TypeScript files without checking their types. To type check a file and everything it imports before Bun runs it, use the --check flag.
If there is a type error, Bun prints it, exits with code 1, and does not run the file. See bun check.
Compare to npm run <script> or yarn <script>
Your package.json can define named "scripts" that correspond to shell commands.
Use bun run <script> to execute these scripts.
Bun executes the script command in a subshell. On Linux & macOS, it checks for the following shells in order, using the first one it finds: bash, sh, zsh. On Windows, it uses the Bun Shell to support bash-like syntax and many common commands.
You can also run scripts with the shorter command 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.
To see a list of available scripts, run bun run without any arguments.
Bun respects lifecycle hooks. For instance, bun run clean runs preclean and postclean, if defined. If the pre<script> fails, Bun does not run the script itself.
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.
By default, Bun respects this shebang and executes the script with node. The --bun flag overrides it: the CLI runs with Bun instead of Node.js.
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
executes <script> in both bar and baz, but not in foo.
bun run - reads JavaScript, TypeScript, TSX, or JSX from stdin and executes it without writing to a temporary file first.
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:
bun run - treats all input as TypeScript with JSX support.
Control the depth of object inspection in console output with the --console-depth flag.
--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.
In memory-constrained environments, use the --smol flag to reduce memory usage at a cost to performance.
--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.
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:
Don't print the script command
Exit without an error if the entrypoint does not exist
Evaluate argument as a script. Alias: -e
Evaluate argument as a script and print the result. Alias: -p
Display this menu and exit. Alias: -h