1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
The `bun` CLI can be used to execute JavaScript/TypeScript files, `package.json` scripts, and [executable packages](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#bin).
## Performance
Bun is designed to start fast and run fast.
Under the hood Bun uses the [JavaScriptCore engine](https://developer.apple.com/documentation/javascriptcore), 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](https://twitter.com/jarredsumner/status/1499225725492076544) than Node.js.
{% table %}
---
- `bun hello.js`
- `5.2ms`
---
- `node hello.js`
- `25.1ms`
{% /table %}
{% caption content="Running a simple Hello World script on Linux" /%}
<!-- {% image src="/images/bun-run-speed.jpeg" caption="Bun vs Node.js vs Deno running Hello World" /%} -->
<!-- ## Speed -->
<!--
Performance sensitive APIs like `Buffer`, `fetch`, and `Response` are heavily profiled and optimized. Under the hood Bun uses the [JavaScriptCore engine](https://developer.apple.com/documentation/javascriptcore), which is developed by Apple for Safari. It starts and runs faster than V8, the engine used by Node.js and Chromium-based browsers. -->
## Run a file
{% callout %}
Compare to `node <file>`
{% /callout %}
Use `bun run` to execute a source file.
```bash
$ 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.
```bash
$ 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.
```bash
$ bun index.tsx
$ bun index.js
```
### `--watch`
To run a file in watch mode, use the `--watch` flag.
```bash
$ bun --watch run index.tsx
```
{% callout %}
**Note** — When using `bun run`, put Bun flags like `--watch` immediately after `bun`.
```bash
$ 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.
{% /callout %}
### `--smol`
In memory-constrained environments, use the `--smol` flag to reduce memory usage at a cost to performance.
```bash
$ bun --smol run index.tsx
```
## Run a `package.json` script
{% note %}
Compare to `npm run <script>` or `yarn <script>`
{% /note %}
```sh
$ bun [bun flags] run <script> [script flags]
```
Your `package.json` can define a number of named `"scripts"` that correspond to shell commands.
```jsonc
{
// ... other fields
"scripts": {
"clean": "rm -rf dist && echo 'Done.'",
"dev": "bun server.ts"
}
}
```
Use `bun run <script>` to execute these scripts.
```bash
$ 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`.
{% callout %}
⚡️ The startup time for `npm run` on Linux is roughly 170ms; with Bun it is `6ms`.
{% /callout %}
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.
```bash
$ bun run dev
```
To see a list of available scripts, run `bun run` without any arguments.
```bash
$ 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](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) to indicate that they should be executed with `node`.
```js
#!/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.
```bash
$ bun run --bun vite
```
|
