| CARVIEW |
Select Language
HTTP/2 308
date: Wed, 28 Jan 2026 22:30:38 GMT
content-type: text/plain
cache-control: public, max-age=0, must-revalidate
location: /docs/runtime
refresh: 0;url=/docs/runtime
server: cloudflare
strict-transport-security: max-age=63072000
x-vercel-id: bom1::d4bzq-1769639438463-6a6e7bb76bdd
cf-cache-status: DYNAMIC
nel: {"report_to":"cf-nel","success_fraction":0.0,"max_age":604800}
report-to: {"group":"cf-nel","max_age":604800,"endpoints":[{"url":"https://a.nel.cloudflare.com/report/v4?s=J5nYyLoCyi8KEEXiHbNSUAO1eLVqhsYWqqK8s3BZkPruFQpcxFrQIrPmZ1DT9Rv%2BdZpwQEXkbPlFTcC2v%2FmZAmrYJI4Ing%3D%3D"}]}
cf-ray: 9c53ef79dd5c165e-BLR
HTTP/2 200
date: Wed, 28 Jan 2026 22:30:38 GMT
content-type: text/html; charset=utf-8
age: 4463
cache-control: no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0
cf-cache-status: DYNAMIC
x-version: dpl_A3HQurgLKtwLN1Gzr1B2bYgwenEo
content-encoding: gzip
content-security-policy: worker-src * blob: data: 'unsafe-eval' 'unsafe-inline'; object-src data: ; base-uri 'self'; upgrade-insecure-requests; frame-ancestors 'self' https://dashboard.mintlify.com; form-action 'self' https://codesandbox.io;
expires: 0
link: ; rel="llms-txt", ; rel="llms-full-txt"
pragma: no-cache
server: cloudflare
strict-transport-security: max-age=63072000
vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch, Accept-Encoding
x-cache-key: bun-1dd33a4e/41/dpl_A3HQurgLKtwLN1Gzr1B2bYgwenEo/docs/runtime#html=html
x-frame-options: DENY
x-llms-txt: /llms.txt
x-matched-path: /_sites/[subdomain]/[[...slug]]
x-mint-proxy-version: 1.0.0-prod
x-mintlify-client-version: 0.0.2419
x-nextjs-prerender: 1
x-nextjs-stale-time: 60
x-powered-by: Next.js
x-served-version: dpl_A3HQurgLKtwLN1Gzr1B2bYgwenEo
x-vercel-cache: MISS
x-vercel-id: bom1:bom1:iad1::iad1::ztstn-1769639438555-85700aec9b85
x-vercel-project-id: prj_ekSYngkqMLMUb1wdarxNSixTj2nj
nel: {"report_to":"cf-nel","success_fraction":0.0,"max_age":604800}
report-to: {"group":"cf-nel","max_age":604800,"endpoints":[{"url":"https://a.nel.cloudflare.com/report/v4?s=3mUT84kp%2FEakTZw1whQ7zQ6zgC%2Bd0WnpBihucEQa0LWXdCPOmyMUzGpNSViEk3BZI8ZNY5rYEuOflBWpa1BCqRA6vrHbFg%3D%3D"}]}
cf-ray: 9c53ef7a6d97165e-BLR
Bun Runtime - Bun
Skip to main content
Core Runtime
File & Module System
Networking
Concurrency
Process & System
Interop & Tooling
Standards & Compatibility
- Run a file
- --watch
- Run a package.json script
- --bun
- Filtering
- bun run - to pipe code from stdin
- bun run --console-depth
- bun run --smol
- Resolution order
- CLI Usage
- General Execution Options
- Workspace Management
- Runtime & Process Control
- Development Workflow
- Debugging
- Dependency & Module Resolution
- Transpilation & Language Features
- Networking & Security
- Global Configuration & Context
- Examples
Core Runtime
Bun Runtime
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.
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.
This benchmark is based on running a simple Hello World script on Linux
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.
Alternatively, you can omit the
To run a file in watch mode, use the
Run a
Your
Use
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:
Scripts can also be run with the shorter command
To see a list of available scripts, run
Bun respects lifecycle hooks. For instance,
It’s common for 
cli.js
By default, Bun respects this shebang and executes the script with
will execute
You can also use
For convenience, all code is treated as TypeScript with JSX support when using
Control the depth of object inspection in console output with the
This sets how deeply nested objects are displayed in 
console.ts
In memory-constrained environments, use the
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
Run a package.json script:
| Command | Time |
|---|---|
bun hello.js | 5.2ms |
node hello.js | 25.1ms |
Run a file
Usebun run to execute a source file.
terminal
Copy
bun run index.js
terminal
Copy
bun run index.js
bun run index.jsx
bun run index.ts
bun run index.tsx
run keyword and use the “naked” command; it behaves identically.
terminal
Copy
bun index.tsx
bun index.js
--watch
To run a file in watch mode, use the --watch flag.
terminal
Copy
bun --watch run index.tsx
When using Flags that occur at the end of the command will be ignored and passed through to the
bun run, put Bun flags like --watch immediately after bun.Copy
bun --watch run dev # ✔️ do this
bun run dev --watch # ❌ don't do this
"dev" script itself.Run a package.json script
Compare to
npm run <script> or yarn <script>Copy
bun [bun flags] run <script> [script flags]
package.json can define a number of named "scripts" that correspond to shell commands.
package.json
Copy
{
// ... other fields
"scripts": {
"clean": "rm -rf dist && echo 'Done.'",
"dev": "bun server.ts"
}
}
bun run <script> to execute these scripts.
terminal
Copy
bun run clean
rm -rf dist && echo 'Done.'
Copy
Cleaning...
Done.
bash, sh, zsh. On Windows, it uses 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>, however if there is a built-in bun command with the same name, the built-in command takes precedence. In this case, use the more explicit bun run <script> command to execute your package script.
terminal
Copy
bun run dev
bun run without any arguments.
terminal
Copy
bun run
Copy
quickstart scripts:
bun run clean
rm -rf dist && echo 'Done.'
bun run dev
bun server.ts
2 scripts
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.
cli.jsCopy
#!/usr/bin/env node
// do stuff
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.
terminal
Copy
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
terminal
Copy
bun run --filter 'ba*' <script>
<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.
terminal
Copy
echo "console.log('Hello')" | bun run -
Copy
Hello
bun run - to redirect files into Bun. For example, to run a .js file as if it were a .ts file:
terminal
Copy
echo "console.log!('This is TypeScript!' as any)" > secretly-typescript.js
bun run - < secretly-typescript.js
Copy
This is TypeScript!
bun run -.
bun run --console-depth
Control the depth of object inspection in console output with the --console-depth flag.
terminal
Copy
bun --console-depth 5 run index.tsx
console.log() output. The default depth is 2. Higher values show more nested properties but may produce verbose output for complex objects.
console.tsCopy
const nested = { a: { b: { c: { d: "deep" } } } };
console.log(nested);
// With --console-depth 2 (default): { a: { b: [Object] } }
// With --console-depth 4: { a: { b: { c: { d: 'deep' } } } }
bun run --smol
In memory-constrained environments, use the --smol flag to reduce memory usage at a cost to performance.
terminal
Copy
bun --smol run index.tsx
--smol flag, so this is mostly useful for cases where you want to make the heap size grow more slowly.
Resolution order
Absolute paths and paths starting with./ or .\\ are always executed as source files. Unless using bun run, running a file with an allowed extension will prefer the file over a package.json script.
When there is a package.json script and a file with the same name, bun run prioritizes the package.json script. The full resolution order is:
- package.json scripts, eg
bun run build - Source files, eg
bun run src/main.js - Binaries from project packages, eg
bun add eslint && bun run eslint - (
bun runonly) System commands, egbun run ls
CLI Usage
Copy
bun run <file or script>
General Execution Options
Don’t print the script command
Exit without an error if the entrypoint does not exist
Evaluate argument as a script. Alias:
-eEvaluate argument as a script and print the result. Alias:
-pDisplay this menu and exit. Alias:
-hWorkspace Management
Number of lines of script output shown when using —filter (default: 10). Set to 0 to show all lines
Run a script in all workspace packages matching the pattern. Alias:
-FRun a script in all workspace packages (from the
workspaces field in package.json)Runtime & Process Control
Force a script or package to use Bun’s runtime instead of Node.js (via symlinking node). Alias:
-bControl the shell used for
package.json scripts. Supports either bun or systemUse less memory, but run garbage collection more often
Expose
gc() on the global object. Has no effect on Bun.gc()Suppress all reporting of the custom deprecation
Determine whether or not deprecation warnings result in errors
Set the process title
Boolean to force
Buffer.allocUnsafe(size) to be zero-filledThrow an error if
process.dlopen is called, and disable export condition node-addonsOne of
strict, throw, warn, none, or
warn-with-error-codeSet the default depth for
console.log object inspection (default: 2)Development Workflow
Automatically restart the process on file change
Enable auto reload in the Bun runtime, test runner, or bundler
Disable clearing the terminal screen on reload when —hot or —watch is enabled
Debugging
Activate Bun’s debugger
Activate Bun’s debugger, wait for a connection before executing
Activate Bun’s debugger, set breakpoint on first line of code and wait
Dependency & Module Resolution
Import a module before other modules are loaded. Alias:
-rAlias of —preload, for Node.js compatibility
Alias of —preload, for Node.js compatibility
Disable auto install in the Bun runtime
Configure auto-install behavior. One of
auto (default, auto-installs when no node_modules),
fallback (missing packages only), force (always)Auto-install dependencies during execution. Equivalent to —install=fallback
Skip staleness checks for packages in the Bun runtime and resolve from disk
Use the latest matching versions of packages in the Bun runtime, always checking npm
Pass custom conditions to resolve
Main fields to lookup in
package.json. Defaults to —target dependentPreserve symlinks when resolving files
Preserve symlinks when resolving the main entry point
Defaults to:
.tsx,.ts,.jsx,.js,.jsonTranspilation & Language Features
Specify custom
tsconfig.json. Default $cwd/tsconfig.jsonSubstitute K:V while parsing, e.g.
—define process.env.NODE_ENV:“development”. Values are parsed as
JSON. Alias: -dRemove function calls, e.g.
—drop=console removes all console.* callsParse files with
.ext:loader, e.g. —loader .js:jsx. Valid loaders: js,
jsx, ts, tsx, json, toml, text,
file, wasm, napi. Alias: -lDisable macros from being executed in the bundler, transpiler and runtime
Changes the function called when compiling JSX elements using the classic JSX runtime
Changes the function called when compiling JSX fragments
Declares the module specifier to be used for importing the jsx and jsxs factory functions. Default:
reactautomatic (default) or classicTreat JSX elements as having side effects (disable pure annotations)
Ignore tree-shaking annotations such as
@PURENetworking & Security
Set the default port for
Bun.servePreconnect to a URL while code is loading
Set the maximum size of HTTP headers in bytes. Default is 16KiB
Set the default order of DNS lookup results. Valid orders:
verbatim (default), ipv4first,
ipv6firstUse the system’s trusted certificate authorities
Use OpenSSL’s default CA store
Use bundled CA store
Preconnect to
$REDIS_URL at startupPreconnect to PostgreSQL at startup
Set the default User-Agent header for HTTP requests
Global Configuration & Context
Load environment variables from the specified file(s)
Absolute path to resolve files & entry points from. This just changes the process’ cwd
Specify path to Bun config file. Default
$cwd/bunfig.toml. Alias: -cExamples
Run a JavaScript or TypeScript file:Copy
bun run ./index.js
bun run ./index.tsx
Copy
bun run dev
bun run lint
Was this page helpful?
⌘I