Use Bun with Astro

Bun is an all-in-one JavaScript runtime & toolkit. See Bun’s documentation for more information.

Caution

Bun recently made their first stable release. However, using Bun with Astro may reveal rough edges. Some integrations may not work as expected. Consult Bun’s official documentation for working with Astro for details.

If you have any problems using Bun, please open an Issue on GitHub with Bun directly.

Prerequisites

Section titled Prerequisites

• Bun installed locally on your machine. See the installation instructions in Bun’s official documentation.

Create a new Astro project with Bun

Section titled Create a new Astro project with Bun

Create a new Astro project with Bun using the following create-astro command:

bunx create-astro@latest my-astro-project-using-bun

Tip

You may also create a new Astro project from any existing Astro GitHub repository using the --template flag:

bunx create-astro@latest my-astro-project-using-bun --template eliancodes/brutal

Install dependencies

Section titled Install dependencies

If you’re starting a new project using bunx create-astro, the CLI will automatically use Bun to install dependencies and you can skip this step.

Otherwise, you’ll need to install your dependencies with Bun:

bun install

Add Types

Section titled Add Types

Bun publishes the bun-types package, containing the runtime types for Bun.

Install bun-types using the following command:

bun add -d bun-types

Add the package to your types in tsconfig.json

tsconfig.json

  "compilerOptions": {
    "types": ["bun-types"]
  }

Using Astro integrations

Section titled Using Astro integrations

You can also use any of the official Astro integrations with the astro add command:

bunx astro add react

Run Astro with Bun

Section titled Run Astro with Bun

Note

Use the --bun CLI flag before every astro command to use Bun’s own runtime in place of Node.

Run the development server

Section titled Run the development server

To run the development server using Bun as the runtime, use the following command:

bunx --bun astro dev

Building your site with Bun

Section titled Building your site with Bun

To build your site using Bun as the runtime, use the following command:

bunx --bun astro build

Astro will output your site to the dist/ directory. Then, you can serve your site using the preview command:

bunx --bun astro preview

Add SSR with Bun using @astrojs/node

Section titled Add SSR with Bun using @astrojs/node

Bun features Node.js API compatibility. Using the @astrojs/node adapter you can add server-side rendering to your Astro project using Bun’s runtime as a replacement for Node.

Run the following command to add the Node.js adapter to your Astro project:

bunx astro add node

Build your site again, using the same build command as above:

bunx --bun astro build

Finally, use the following command to run your built site.

bun ./dist/server/entry.mjs

Testing in Bun

Section titled Testing in Bun

Bun ships with a fast, built-in, Jest-compatible test runner through the bun test command. If you like to use that read bun test documentation.

However, it is also possible to use Cypress or Playwright for a modern approach to testing web apps.

Cypress

Section titled Cypress

Cypress is a front-end testing tool and is on a mission to “make the testing experience enjoyable and generate developer happiness”. This enables you to write end-to-end tests for your Astro site.

Install Cypress with the following command:

bun add cypress --dev

For the rest of the configuration and to start your first test, follow the rest of Cypress process in the Astro Testing Guide.

Playwright

Section titled Playwright

Playwright is an end-to-end testing framework that allows you to test your Astro code on all modern rendering engines including Chromium, WebKit, and Firefox.

Install Playwright using the following command:

bun create playwright

To create your first Playwright test, follow the intructions for the rest of the Playwright process in the Astro Testing Guide.

Official Resources

Section titled Official Resources

• Build an app with Astro and Bun

Community Resources

Section titled Community Resources

Using Bun with Astro? Add your blog post or video to this page!

• Building a Cloudflare Pages site with Bun - blog post