What is the bun run command?

Key takeaways

• Bun is a toolkit for JavaScript and TypeScript development, serving as an alternative to Node.js's npm. It features a runtime based on Apple’s JavaScriptCore engine.

• The bun run command executes JavaScript and TypeScript files, supporting various flags such as –watch for real-time updates during development and –smol for reduced memory usage at the cost of performance. It also allows running scripts defined in package.json files, similar to npm or yarn.

• Bun maintains compatibility with Node.js conventions, making it easy for developers to transition. It handles conflicts between script keywords and built-in commands gracefully, providing a familiar and efficient environment for executing scripts and applications.

Bun is a toolkit designed to streamline the development process for JavaScript and TypeScript applications, acting as an alternative to Node.js's npm. It includes a runtime, which is the environment that allows you to execute JavaScript and TypeScript code. Unlike Node.js, which uses the V8 engine from Chromium, Bun's runtime is built on Apple's JavaScriptCore engine, which powers Safari. One of Bun’s key features is its CLI (command-line interface), which includes the bun run command. This command allows developers to execute scripts or files within Bun’s runtime environment, offering a faster and more efficient alternative for running JavaScript and TypeScript projects.

Using the bun run command

We can use this keyword in multiple ways. We can pass it the different files that we want to execute along with the flags that we want. Let's take a look at the different semantics of this command.

Running a file

The syntax for executing a file using this command is as follows:

As compared to the node command, this command also takes the file name as an argument and supports all JavaScript and TypeScript file extensions. Alternatively, we can also omit the run in the command and use it as follows:

A major difference between using bun run and node is that of performance. As Bun's runtime is written in ZigIt is a low-level systems programming language that is used for maintaining software., this gives it a huge performance boost over Node.js, with startup times four times faster than those of Node.js. Let's take a look at some of the flags that we can use with this command.

• The –watch flag

This flag runs the file in watch mode. This enables any changes made in the file to be reflected in real time, without having to re-run the file. Here's how it is used with the command:

Note: This command hard resets the entire started process and runs it from scratch. However, if we use the –hot flag, Bun will only detect the changes made inside the code and update its internal module cache with the new code.

• The –smol flag

This flag is used for environments with a constraint on memory. It reduces memory usage but this comes as a trade-off for less performance. Here's how we can use it:

Running package.json files

Similar to how we run files using npm or yarn, Bun also allows us to run package.json files and use the scripts defined inside the file. The scripts inside the package.json file are shell commands that Bun will execute in the root of the project directory. Here's how we can use bun run to run those scripts:

Let us assume that the scripts field inside our package.json file looks like the following:

We can use the following command to execute the commands defined by the keyword clean:

Note: If there's a conflict between the script keyword and a built-in bun command, the built-in command will take precedence. In this case, the entire bun run <script> command should be utilized instead of bun <script>.

Oftentimes, the package.json scripts will contain references to locally installed CLIs such as vite or next. These are indicated by a 'shebang'It is a character sequence denoted by a number sign followed by an exclamation mark (#!).. This indicates that these scripts should be executed with Node instead of the Bun CLI. If we want to override the shebang, we can use the following flag:

You can try all of the commands you learned in the widget below:

Here's a recap of all the commands that you can test in the widget:

Conclusion

In this Answer, we had a look at how we can use the bun run command to execute JavaScript and TypeScript files. We also saw how we can execute the scripts field inside the package.json file using the bun run command. It is evident that Bun's runtime is very similar to the very commonly used Node's runtime environment–this makes it extremely easy to understand and use.