aboutsummaryrefslogtreecommitdiff
path: root/docs/cli/run.md
blob: 3680573b06a10f29859e1b2772af2ea2ddb7285a (plain) (blame)
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
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).

<!-- ## 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
```

The "naked" `bun` command is equivalent to `bun run`.

```bash
$ bun index.tsx
```

### `--watch`

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

```bash
$ bun --watch run index.tsx
```

### `--smol`

{% callout %}
Added in Bun v0.7.0.
{% /callout %}

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 %}

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 <script>` to execute these scripts.

```bash
$ bun 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.

## Environment variables

Bun automatically loads environment variables from `.env` files before running a file, script, or executable. The following files are checked, in order:

1. `.env.local` (first)
2. `NODE_ENV` === `"production"` ? `.env.production` : `.env.development`
3. `.env`

To debug environment variables, run `bun run env` to view a list of resolved environment variables.

## 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.

{% image src="/images/bun-run-speed.jpeg" caption="Bun vs Node.js vs Deno running Hello World" /%}

<!-- If no `node_modules` directory is found in the working directory or above, Bun will abandon Node.js-style module resolution in favor of the `Bun module resolution algorithm`. Under Bun-style module resolution, all packages are _auto-installed_ on the fly into a [global module cache](/docs/install/cache). For full details on this algorithm, refer to [Runtime > Modules](/docs/runtime/modules). -->
>Gravatar Jarred Sumner 1-1/+1 2022-03-16Update Dockerfile.baseGravatar Jarred Sumner 1-0/+1 2022-03-16Update MakefileGravatar Jarred Sumner 1-2/+23 2022-03-16cleanup error printingGravatar Jarred Sumner 7-105/+193 2022-03-16Revert "Unlimited arguments in process.nextTick"Gravatar Jarred Sumner 1-38/+48 2022-03-16bun.lockbGravatar Jarred Sumner 3-0/+0 2022-03-16Update feature_flags.zigGravatar Jarred Sumner 1-0/+1 2022-03-16[bun.js] Bun.unsafe test should check the gcGravatar Jarred Sumner 1-4/+14 2022-03-16Update work_pool.zigGravatar Jarred Sumner 1-21/+28 2022-03-16Add a way to run serial tasks on a different threadGravatar Jarred Sumner 1-3/+65 2022-03-16fix crash when SyntaxError is thrown and we did not receive an ErrorInstance?Gravatar Jarred Sumner 1-18/+25 2022-03-16[bun.js] Fix release-mode test failures in HeadersGravatar Jarred Sumner 1-47/+42 2022-03-16Update ref_count.zigGravatar Jarred Sumner 1-2/+0 2022-03-15file is too bigjarred/replGravatar Jarred Sumner 1-113827/+0 2022-03-15Update Dockerfile.baseGravatar Jarred Sumner 1-1/+1 2022-03-15Add rust and lolhtml to dockerfileGravatar Jarred Sumner 2-0/+20 2022-03-15bump webkitGravatar Jarred Sumner 1-1/+1 2022-03-15Update WebKitGravatar Jarred Sumner 1-0/+0 2022-03-15:camera:Gravatar Jarred Sumner 60-799/+859 2022-03-15Fix test failureGravatar Jarred Sumner 1-15/+17 2022-03-15[bun:error] handle errors without a name or messageGravatar Jarred Sumner 1-6/+11 2022-03-15Update pool.zigGravatar Jarred Sumner 1-0/+1 2022-03-15Load .env by defaultGravatar Jarred Sumner 2-0/+8 2022-03-15mimalloc interpose is buggyGravatar Jarred Sumner 1-2/+25 2022-03-15higher max http requests for bun.jsGravatar Jarred Sumner 1-0/+29 2022-03-15zero copyGravatar Jarred Sumner 1-21/+15 2022-03-15Update javascript.zigGravatar Jarred Sumner 1-2/+0 2022-03-15[bun.js] utf8 console.{time, count, timeEnd, profile, profileEnd, count, cou...Gravatar Jarred Sumner 1-16/+16