bun

bun is a new:

• JavaScript runtime with Web APIs like fetch, WebSocket, and several more built-in. bun embeds JavaScriptCore, which tends to be faster and more memory efficient than more popular engines like V8 (though harder to embed)
• JavaScript/TypeScript/JSX transpiler
• JavaScript & CSS bundler
• Task runner for package.json scripts
• npm-compatible package manager

All in one fast & easy-to-use tool. Instead of 1,000 node_modules for development, you only need bun.

bun is experimental software. Join bun’s Discord for help and have a look at things that don’t work yet.

Today, bun's primary focus is bun.js: bun's JavaScript runtime.

Install

Native: (macOS x64 & Silicon, Linux x64, Windows Subsystem for Linux)

curl -fsSL https://bun.sh/install | bash

npm:

npm install -g bun

Homebrew: (MacOS and Linux)

brew tap oven-sh/bun
brew install bun

Docker: (Linux x64)

docker pull jarredsumner/bun:edge
docker run --rm --init --ulimit memlock=-1:-1 jarredsumner/bun:edge

If using Linux, kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1.

Upgrade

To upgrade to the latest version of Bun, run:

bun upgrade

Bun automatically releases a canary build on every commit to main. To upgrade to the latest canary build, run:

bun upgrade --canary

View canary build

^{Canary builds are released without automated tests}

Table of Contents

• Install
• Using bun.js - a new JavaScript runtime environment
  • Types for bun.js (editor autocomplete)
  • Fast paths for Web APIs
• Using bun as a package manager
• Using bun as a task runner
• Creating a Discord bot with Bun
  • Application Commands
• Using bun with Next.js
• Using bun with single page apps
  • Using bun with Create React App
• Using bun with TypeScript
  • Transpiling TypeScript with Bun
  • Adding Type Definitions
• Not implemented yet
  • Limitations & intended usage
  • Upcoming breaking changes
• Configuration
  • bunfig.toml
  • Loaders
  • CSS in JS
    • When platform is browser
    • When platform is bun
  • CSS Loader
  • CSS runtime
  • Frameworks
• Troubleshooting
  • bun not running on an M1 (or Apple Silicon)
  • error: Unexpected
  • bun install is stuck
  • Unzip is required
    • Debian / Ubuntu / Mint
    • RedHat / CentOS / Fedora
    • Arch / Manjaro
    • OpenSUSE
• Reference
  • bun install
    • Configuring bun install with bunfig.toml
    • Configuring with environment variables
    • Platform-specific dependencies?
    • Peer dependencies?
    • Lockfile
    • Why is it binary?
    • How do I inspect it?
    • What does the lockfile store?
    • Why is it fast?
    • Cache
    • npm registry metadata
  • bun run
  • bun create
    • Usage
    • Local templates
    • Flags
    • Publishing a new template
    • Testing your new template
    • Config
    • How bun create works
  • bun init
  • bun bun
    • Why bundle?
    • What is .bun?
    • Position-independent code
    • Where is the code?
    • Advanced
    • What is the module ID hash?
  • bun upgrade
  • bun completions
• Bun.serve - fast HTTP server
  • Usage
  • HTTPS
  • WebSockets
  • Error handling
• Bun.write – optimizing I/O
• Bun.spawn - spawn processes
• Bun.which - find the path to a bin
• bun:sqlite (SQLite3 module)
  • bun:sqlite Benchmark
  • Getting started with bun:sqlite
  • Database
    • Database.prototype.query
    • Database.prototype.prepare
    • Database.prototype.exec & Database.prototype.run
    • Database.prototype.serialize
    • Database.prototype.loadExtension
  • Statement
    • Statement.all
    • Statement.values
    • Statement.get
    • Statement.run
    • Statement.finalize
    • Statement.toString()
  • Datatypes
• bun:ffi (Foreign Functions Interface)
  • Low-overhead FFI
  • Usage
  • Supported FFI types (FFIType)
  • Strings (CString)
    • Returning a string
  • Function pointers (CFunction)
  • Pointers
    • Passing a pointer
    • Reading pointers
    • Not implemented yet
• Node-API (napi)
• Bun.Transpiler
  • Bun.Transpiler.transformSync
  • Bun.Transpiler.transform
  • Bun.Transpiler.scan
  • Bun.Transpiler.scanImports
• Bun.peek - read a promise same-tick
• Bun.dns - lookup a domain
• Module resolution in Bun
• Environment variables
• Credits
• License
• Developing bun
  • Dev Container (Linux/Windows)
  • MacOS
    • Build bun (macOS)
    • Verify it worked (macOS)
    • Troubleshooting (macOS)
  • Troubleshooting (general)
• vscode-zig

Using bun.js - a new JavaScript runtime environment

bun.js focuses on performance, developer experience and compatibility with the JavaScript ecosystem.

// http.ts
export default {
  port: 3000,
  fetch(request: Request) {
    return new Response("Hello World");
  },
};

// bun ./http.ts

./http_load_test  20 127.0.0.1 3000

bun.js prefers Web API compatibility instead of designing new APIs when possible. bun.js also implements some Node.js APIs.

• TypeScript & JSX support is built-in, powered by Bun's JavaScript transpiler
• ESM & CommonJS modules are supported (internally, bun.js uses ESM)
• Many npm packages "just work" with bun.js (when they use few/no node APIs)
• tsconfig.json "paths" is natively supported, along with "exports" in package.json
• fs, path, and process from Node are partially implemented
• Web APIs like fetch, Response, URL and more are built-in
• HTMLRewriter makes it easy to transform HTML in bun.js
• Starts 4x faster than Node (try it yourself)
• .env files automatically load into process.env and Bun.env
• top level await

The runtime uses JavaScriptCore, the JavaScript engine powering WebKit and Safari. Some web APIs like Headers and URL directly use Safari's implementation.

cat clone that runs 2x faster than GNU cat for large files on Linux

// cat.js
import { resolve } from "path";
import { write, stdout, file, argv } from "bun";

const path = resolve(argv.at(-1));

await write(
  // stdout is a Blob
  stdout,
  // file(path) returns a Blob - https://developer.mozilla.org/en-US/docs/Web/API/Blob
  file(path),
);

// bun ./cat.js ./path-to-file

Read lines from standard input:

// As of Bun v0.3.0, console is an AsyncIterable
for await (const line of console) {
  // line of text from stdin
  console.log(line);
}

Server-side render React:

import { renderToReadableStream } from "react-dom/server";

const dt = new Intl.DateTimeFormat();

export default {
  port: 3000,
  async fetch(request: Request) {
    return new Response(
      await renderToReadableStream(
        <html>
          <head>
            <title>Hello World</title>
          </head>
          <body>
            <h1>Hello from React!</h1>
            <p>The date is {dt.format(new Date())}</p>
          </body>
        </html>,
      ),
    );
  },
};

Write to stdout with console.write:

// no trailing newline
// works with strings and typed arrays
console.write("Hello World!");

There are some more examples in the examples folder.

PRs adding more examples are very welcome!

Types for bun.js (editor autocomplete)

The best docs right now are the TypeScript types in the bun-types npm package. A docs site is coming soon.

To get autocomplete for bun.js types in your editor,

1. Install the bun-types npm package:

# yarn/npm/pnpm work too, "bun-types" is an ordinary npm package
bun add bun-types

2. Add this to your tsconfig.json or jsconfig.json:

{
  "compilerOptions": {
    "lib": ["ESNext"],
    "module": "esnext",
    "target": "esnext",
    "moduleResolution": "node",
    // "bun-types" is the important part
    "types": ["bun-types"]
  }
}

You can also view the types here.

To contribute to the types, head over to packages/bun-types.

Fast paths for Web APIs

bun.js has fast paths for common use cases that make Web APIs live up to the performance demands of servers and CLIs.

Bun.file(path) returns a Blob that represents a lazily-loaded file.

When you pass a file blob to Bun.write, Bun automatically uses a faster system call:

const blob = Bun.file("input.txt");
await Bun.write("output.txt", blob);

On Linux, this uses the copy_file_range syscall and on macOS, this becomes clonefile (or fcopyfile).

Bun.write also supports Response objects. It automatically converts to a Blob.

// Eventually, this will stream the response to disk but today it buffers
await Bun.write("index.html", await fetch("https://example.com"));

Using bun as a package manager

On Linux, bun install tends to install packages 20x - 100x faster than npm install. On macOS, it’s more like 4x - 80x.

To install packages from package.json:

bun install

To add or remove packages from package.json:

bun remove react
bun add preact

# If this returns a version >= 5.6, you don't need to do anything
uname -r

# Install the official Ubuntu hardware enablement kernel
sudo apt install --install-recommends linux-generic-hwe-20.04

Using bun as a task runner

Instead of waiting 170ms for your npm client to start for each task, you wait 6ms for bun.

To use bun as a task runner, run bun run instead of npm run.

# Instead of "npm run clean"
bun run clean

# This also works
bun clean

Assuming a package.json with a "clean" command in "scripts":

{
  "name": "myapp",
  "scripts": {
    "clean": "rm -rf dist out node_modules"
  }
}

Creating a Discord bot with Bun

Application Commands

Application commands are native ways to interact with apps in the Discord client. There are 3 types of commands accessible in different interfaces: the chat input, a message's context menu (top-right menu or right-clicking in a message), and a user's context menu (right-clicking on a user).

To get started you can use the interactions template:

bun create discord-interactions my-interactions-bot
cd my-interactions-bot

If you don't have a Discord bot/application yet, you can create one here (https://discord.com/developers/applications/me).

Invite bot to your server by visiting https://discord.com/api/oauth2/authorize?client_id=<your_application_id>&scope=bot%20applications.commands

Afterwards you will need to get your bot's token, public key, and application id from the application page and put them into .env.example file

Then you can run the http server that will handle your interactions:

bun install
mv .env.example .env

bun run.js # listening on port 1337

Discord does not accept an insecure HTTP server, so you will need to provide an SSL certificate or put the interactions server behind a secure reverse proxy. For development, you can use ngrok/cloudflare tunnel to expose local ports as secure URL.

Using bun with Next.js

To create a new Next.js app with bun:

bun create next ./app
cd app
bun dev # start dev server

To use an existing Next.js app with bun:

bun add bun-framework-next
echo "framework = 'next'" > bunfig.toml
bun bun # bundle dependencies
bun dev # start dev server

Many of Next.js’ features are supported, but not all.

Here’s what doesn’t work yet:

• getStaticPaths
• same-origin fetch inside of getStaticProps or getServerSideProps
• locales, zones, assetPrefix (workaround: change --origin \"http://localhost:3000/assetPrefixInhere\")
• next/image is polyfilled to a regular <img src> tag.
• proxy and anything else in next.config.js
• API routes, middleware (middleware is easier to support, though! Similar SSR API)
• styled-jsx (technically not Next.js, but often used with it)
• React Server Components

When using Next.js, bun automatically reads configuration from .env.local, .env.development and .env (in that order). process.env.NEXT_PUBLIC_ and process.env.NEXT_ automatically are replaced via --define.

Currently, any time you import new dependencies from node_modules, you will need to re-run bun bun --use next. This will eventually be automatic.

Using bun with single-page apps

In your project folder root (where package.json is):

bun bun ./entry-point-1.js ./entry-point-2.jsx
bun

By default, bun will look for any HTML files in the public directory and serve that. For browsers navigating to the page, the .html file extension is optional in the URL, and index.html will automatically rewrite for the directory.

Here are examples of routing from public/ and how they’re matched:

If public/index.html exists, it becomes the default page instead of a 404 page, unless that pathname has a file extension.

Using bun with Create React App

To create a new React app:

bun create react ./app
cd app
bun dev # start dev server

To use an existing React app:

# To enable React Fast Refresh, ensure it is installed
bun add -d react-refresh

# Generate a bundle for your entry point(s)
bun bun ./src/index.js # jsx, tsx, ts also work. can be multiple files

# Start the dev server
bun dev

From there, bun relies on the filesystem for mapping dev server paths to source files. All URL paths are relative to the project root (where package.json is located).

Here are examples of routing source code file paths:

You do not need to include file extensions in import paths. CommonJS-style import paths without the file extension work.

You can override the public directory by passing --public-dir="path-to-folder".

If no directory is specified and ./public/ doesn’t exist, bun will try ./static/. If ./static/ does not exist, but won’t serve from a public directory. If you pass --public-dir=./ bun will serve from the current directory, but it will check the current directory last instead of first.

Using bun with TypeScript

Transpiling TypeScript with Bun

TypeScript just works. There’s nothing to configure and nothing extra to install. If you import a .ts or .tsx file, bun will transpile it into JavaScript. bun also transpiles node_modules containing .ts or .tsx files. This is powered by bun’s TypeScript transpiler, so it’s fast.

bun also reads tsconfig.json, including baseUrl and paths.

Adding Type Definitions

To get TypeScript working with the global API, add bun-types to your project:

bun add -d bun-types

And to the types field in your tsconfig.json:

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

Not implemented yet

bun is a project with an incredibly large scope and is still in its early days.

You can see Bun's Roadmap, but here are some additional things that are planned:

Limitations & intended usage

Today, bun is mostly focused on bun.js: the JavaScript runtime.

While you could use bun's bundler & transpiler separately to build for browsers or node, bun doesn't have a minifier or support tree-shaking yet. For production browser builds, you probably should use a tool like esbuild or swc.

Longer-term, bun intends to replace Node.js, Webpack, Babel, yarn, and PostCSS (in production).

Upcoming breaking changes

• Bun's CLI flags will change to better support bun as a JavaScript runtime. They were chosen when bun was just a frontend development tool.
• Bun's bundling format will change to accommodate production browser bundles and on-demand production bundling

Configuration

bunfig.toml

bunfig.toml is bun's configuration file.

It lets you load configuration from a file instead of passing flags to the CLI each time. The config file is loaded before CLI arguments are parsed, which means CLI arguments can override them.

Here is an example:

# Set a default framework to use
# By default, bun will look for an npm package like `bun-framework-${framework}`, followed by `${framework}`
framework = "next"
logLevel = "debug"

# publicDir = "public"
# external = ["jquery"]

[macros]
# Remap any import like this:
#     import {graphql} from 'react-relay';
# To:
#     import {graphql} from 'macro:bun-macro-relay';
react-relay = { "graphql" = "bun-macro-relay" }

[bundle]
saveTo = "node_modules.bun"
# Don't need this if `framework` is set, but showing it here as an example anyway
entryPoints = ["./app/index.ts"]

[bundle.packages]
# If you're bundling packages that do not actually live in a `node_modules` folder or do not have the full package name in the file path, you can pass this to bundle them anyway
"@bigapp/design-system" = true

[dev]
# Change the default port from 3000 to 5000
# Also inherited by Bun.serve
port = 5000

[define]
# Replace any usage of "process.env.bagel" with the string `lox`.
# The values are parsed as JSON, except single-quoted strings are supported and `'undefined'` becomes `undefined` in JS.
# This will probably change in a future release to be just regular TOML instead. It is a holdover from the CLI argument parsing.
"process.env.bagel" = "'lox'"

[loaders]
# When loading a .bagel file, run the JS parser
".bagel" = "js"

[debug]
# When navigating to a blob: or src: link, open the file in your editor
# If not, it tries $EDITOR or $VISUAL
# If that still fails, it will try Visual Studio Code, then Sublime Text, then a few others
# This is used by Bun.openInEditor()
editor = "code"

# List of editors:
# - "subl", "sublime"
# - "vscode", "code"
# - "textmate", "mate"
# - "idea"
# - "webstorm"
# - "nvim", "neovim"
# - "vim","vi"
# - "emacs"
# - "atom"
# If you pass it a file path, it will open with the file path instead
# It will recognize non-GUI editors, but I don't think it will work yet

TODO: list each property name

Loaders

A loader determines how to map imports & file extensions to transforms and output.

Currently, bun implements the following loaders:

Everything else is treated as file. file replaces the import with a URL (or a path).

You can configure which loaders map to which extensions by passing --loaders to bun. For example:

bun --loader=.js:js

This will disable JSX transforms for .js files.

CSS in JS (bun dev only)

When importing CSS in JavaScript-like loaders, CSS is treated special.

By default, bun will transform a statement like this:

import "../styles/global.css";

When platform is browser

globalThis.document?.dispatchEvent(
  new CustomEvent("onimportcss", {
    detail: "http://localhost:3000/styles/globals.css",
  }),
);

An event handler for turning that into a <link> is automatically registered when HMR is enabled. That event handler can be turned off either in a framework’s package.json or by setting globalThis["Bun_disableCSSImports"] = true; in client-side code. Additionally, you can get a list of every .css file imported this way via globalThis["__BUN"].allImportedStyles.

When platform is bun

//@import url("http://localhost:3000/styles/globals.css");

Additionally, bun exposes an API for SSR/SSG that returns a flat list of URLs to css files imported. That function is Bun.getImportedStyles().

// This specifically is for "framework" in package.json when loaded via `bun dev`
// This API needs to be changed somewhat to work more generally with Bun.js
// Initially, you could only use bun.js through `bun dev`
// and this API was created at that time
addEventListener("fetch", async (event: FetchEvent) => {
  let route = Bun.match(event);
  const App = await import("pages/_app");

  // This returns all .css files that were imported in the line above.
  // It’s recursive, so any file that imports a CSS file will be included.
  const appStylesheets = bun.getImportedStyles();

  // ...rest of code
});

This is useful for preventing flash of unstyled content.

CSS Loader

bun bundles .css files imported via @import into a single file. It doesn’t autoprefix or minify CSS today. Multiple .css files imported in one JavaScript file will not be bundled into one file. You’ll have to import those from a .css file.

This input:

@import url("./hi.css");
@import url("./hello.css");
@import url("./yo.css");

Becomes:

/* hi.css */
/* ...contents of hi.css */
/* hello.css */
/* ...contents of hello.css */
/* yo.css */
/* ...contents of yo.css */

CSS runtime

To support hot CSS reloading, bun inserts @supports annotations into CSS that tag which files a stylesheet is composed of. Browsers ignore this, so it doesn’t impact styles.

By default, bun’s runtime code automatically listens to onimportcss and will insert the event.detail into a <link rel="stylesheet" href={${event.detail}}> if there is no existing link tag with that stylesheet. That’s how bun’s equivalent of style-loader works.

Frameworks

Frameworks preconfigure bun to enable developers to use bun with their existing tooling.

Frameworks are configured via the framework object in the package.json of the framework (not in the application’s package.json):

Here is an example:

{
  "name": "bun-framework-next",
  "version": "0.0.0-18",
  "description": "",
  "framework": {
    "displayName": "Next.js",
    "static": "public",
    "assetPrefix": "_next/",
    "router": {
      "dir": ["pages", "src/pages"],
      "extensions": [".js", ".ts", ".tsx", ".jsx"]
    },
    "css": "onimportcss",
    "development": {
      "client": "client.development.tsx",
      "fallback": "fallback.development.tsx",
      "server": "server.development.tsx",
      "css": "onimportcss",
      "define": {
        "client": {
          ".env": "NEXT_PUBLIC_",
          "defaults": {
            "process.env.__NEXT_TRAILING_SLASH": "false",
            "process.env.NODE_ENV": "\"development\"",
            "process.env.__NEXT_ROUTER_BASEPATH": "''",
            "process.env.__NEXT_SCROLL_RESTORATION": "false",
            "process.env.__NEXT_I18N_SUPPORT": "false",
            "process.env.__NEXT_HAS_REWRITES": "false",
            "process.env.__NEXT_ANALYTICS_ID": "null",
            "process.env.__NEXT_OPTIMIZE_CSS": "false",
            "process.env.__NEXT_CROSS_ORIGIN": "''",
            "process.env.__NEXT_STRICT_MODE": "false",
            "process.env.__NEXT_IMAGE_OPTS": "null"
          }
        },
        "server": {
          ".env": "NEXT_",
          "defaults": {
            "process.env.__NEXT_TRAILING_SLASH": "false",
            "process.env.__NEXT_OPTIMIZE_FONTS": "false",
            "process.env.NODE_ENV": "\"development\"",
            "process.env.__NEXT_OPTIMIZE_IMAGES": "false",
            "process.env.__NEXT_OPTIMIZE_CSS": "false",
            "process.env.__NEXT_ROUTER_BASEPATH": "''",
            "process.env.__NEXT_SCROLL_RESTORATION": "false",
            "process.env.__NEXT_I18N_SUPPORT": "false",
            "process.env.__NEXT_HAS_REWRITES": "false",
            "process.env.__NEXT_ANALYTICS_ID": "null",
            "process.env.__NEXT_CROSS_ORIGIN": "''",
            "process.env.__NEXT_STRICT_MODE": "false",
            "process.env.__NEXT_IMAGE_OPTS": "null",
            "global": "globalThis",
            "window": "undefined"
          }
        }
      }
    }
  }
}

Here are type definitions:

type Framework = Environment & {
  // This changes what’s printed in the console on load
  displayName?: string;

  // This allows a prefix to be added (and ignored) to requests.
  // Useful for integrating an existing framework that expects internal routes to have a prefix
  // e.g. "_next"
  assetPrefix?: string;

  development?: Environment;
  production?: Environment;

  // The directory used for serving unmodified assets like fonts and images
  // Defaults to "public" if exists, else "static", else disabled.
  static?: string;

  // "onimportcss" disables the automatic "onimportcss" feature
  // If the framework does routing, you may want to handle CSS manually
  // "facade" removes CSS imports from JavaScript files,
  //    and replaces an imported object with a proxy that mimics CSS module support without doing any class renaming.
  css?: "onimportcss" | "facade";

  // bun’s filesystem router
  router?: Router;
};

type Define = {
  // By passing ".env", bun will automatically load .env.local, .env.development, and .env if exists in the project root
  //    (in addition to the processes’ environment variables)
  // When "*", all environment variables will be automatically injected into the JavaScript loader
  // When a string like "NEXT_PUBLIC_", only environment variables starting with that prefix will be injected

  ".env": string | "*";

  // These environment variables will be injected into the JavaScript loader
  // These are the equivalent of Webpack’s resolve.alias and esbuild’s --define.
  // Values are parsed as JSON, so they must be valid JSON. The only exception is '' is a valid string, to simplify writing stringified JSON in JSON.
  // If not set, `process.env.NODE_ENV` will be transformed into "development".
  defaults: Record<string, string>;
};

type Environment = {
  // This is a wrapper for the client-side entry point for a route.
  // This allows frameworks to run initialization code on pages.
  client: string;
  // This is a wrapper for the server-side entry point for a route.
  // This allows frameworks to run initialization code on pages.
  server: string;
  // This runs when "server" code fails to load due to an exception.
  fallback: string;

  // This is how environment variables and .env is configured.
  define?: Define;
};

// bun’s filesystem router
// Currently, bun supports pages by either an absolute match or a parameter match.
// pages/index.tsx will be executed on navigation to "/" and "/index"
// pages/posts/[id].tsx will be executed on navigation to "/posts/123"
// Routes & parameters are automatically passed to `fallback` and `server`.
type Router = {
  // This determines the folder to look for pages
  dir: string[];

  // These are the allowed file extensions for pages.
  extensions?: string[];
};

To use a framework, you pass bun bun --use package-name.

Your framework’s package.json name should start with bun-framework-. This is so that people can type something like bun bun --use next and it will check bun-framework-next first. This is similar to how Babel plugins tend to start with babel-plugin-.

For developing frameworks, you can also do bun bun --use ./relative-path-to-framework.

If you’re interested in adding a framework integration, please reach out. There’s a lot here, and it’s not entirely documented yet.

Troubleshooting

bun not running on an M1 (or Apple Silicon)

If you see a message like this

[1] 28447 killed bun create next ./test

It most likely means you’re running bun’s x64 version on Apple Silicon. This happens if bun is running via Rosetta. Rosetta is unable to emulate AVX2 instructions, which bun indirectly uses.

The fix is to ensure you installed a version of bun built for Apple Silicon.

error: Unexpected

If you see an error like this:

It usually means the max number of open file descriptors is being explicitly set to a low number. By default, bun requests the max number of file descriptors available (which on macOS, is something like 32,000). But, if you previously ran into ulimit issues with, e.g., Chokidar, someone on The Internet may have advised you to run ulimit -n 8096.

That advice unfortunately lowers the hard limit to 8096. This can be a problem in large repositories or projects with lots of dependencies. Chokidar (and other watchers) don’t seem to call setrlimit, which means they’re reliant on the (much lower) soft limit.

To fix this issue:

1. Remove any scripts that call ulimit -n and restart your shell.
2. Try again, and if the error still occurs, try setting ulimit -n to an absurdly high number, such as ulimit -n 2147483646
3. Try again, and if that still doesn’t fix it, open an issue

Unzip is required

Unzip is required to install bun on Linux. You can use one of the following commands to install unzip:

Debian / Ubuntu / Mint

sudo apt install unzip

RedHat / CentOS / Fedora

sudo dnf install unzip

Arch / Manjaro

sudo pacman -S unzip

OpenSUSE

sudo zypper install unzip

bun install is stuck

Please run bun install --verbose 2> logs.txt and send them to me in bun's discord. If you're on Linux, it would also be helpful if you run sudo perf trace bun install --silent and attach the logs.

Reference

bun install

bun install is a fast package manager & npm client.

bun install can be configured via bunfig.toml, environment variables, and CLI flags.

Configuring bun install with bunfig.toml

bunfig.toml is searched for in the following paths on bun install, bun remove, and bun add:

1. $XDG_CONFIG_HOME/.bunfig.toml or $HOME/.bunfig.toml
2. ./bunfig.toml

^{If both are found, the results are merged together.}

Configuring with bunfig.toml is optional. bun tries to be zero configuration in general, but that's not always possible.

# Using scoped packages with bun install
[install.scopes]

# Scope name      The value can be a URL string or an object
"@mybigcompany" = { token = "123456", url = "https://registry.mybigcompany.com" }
# URL is optional and fallsback to the default registry

# The "@" in the scope is optional
mybigcompany2 = { token = "123456" }

# Environment variables can be referenced as a string that starts with $ and it will be replaced
mybigcompany3 = { token = "$npm_config_token" }

# Setting username and password turns it into a Basic Auth header by taking base64("username:password")
mybigcompany4 = { username = "myusername", password = "$npm_config_password", url = "https://registry.yarnpkg.com/" }
# You can set username and password in the registry URL. This is the same as above.
mybigcompany5 = "https://username:[email protected]/"

# You can set a token for a registry URL:
mybigcompany6 = "https://:[email protected]/"

[install]
# Default registry
# can be a URL string or an object
registry = "https://registry.yarnpkg.com/"
# as an object
#registry = { url = "https://registry.yarnpkg.com/", token = "123456" }

# Install for production? This is the equivalent to the "--production" CLI argument
production = false

# Don't actually install
dryRun = true

# Install optionalDependencies (default: true)
optional = true

# Install local devDependencies (default: true)
dev = true

# Install peerDependencies (default: false)
peer = false

# When using `bun install -g`, install packages here
globalDir = "~/.bun/install/global"

# When using `bun install -g`, link package bins here
globalBinDir = "~/.bun/bin"

# cache-related configuration
[install.cache]
# The directory to use for the cache
dir = "~/.bun/install/cache"

# Don't load from the global cache.
# Note: bun may still write to node_modules/.cache
disable = false

# Always resolve the latest versions from the registry
disableManifest = false


# Lockfile-related configuration
[install.lockfile]

# Print a yarn v1 lockfile
# Note: it does not load the lockfile, it just converts bun.lockb into a yarn.lock
print = "yarn"

# Path to read bun.lockb from
path = "bun.lockb"

# Path to save bun.lockb to
savePath = "bun.lockb"

# Save the lockfile to disk
save = true

If it's easier to read as TypeScript types:

export interface Root {
  install: Install;
}

export interface Install {
  scopes: Scopes;
  registry: Registry;
  production: boolean;
  dryRun: boolean;
  optional: boolean;
  dev: boolean;
  peer: boolean;
  globalDir: string;
  globalBinDir: string;
  cache: Cache;
  lockfile: Lockfile;
  logLevel: "debug" | "error" | "warn";
}

type Registry =
  | string
  | {
      url?: string;
      token?: string;
      username?: string;
      password?: string;
    };

type Scopes = Record<string, Registry>;

export interface Cache {
  dir: string;
  disable: boolean;
  disableManifest: boolean;
}

export interface Lockfile {
  print?: "yarn";
  path: string;
  savePath: string;
  save: boolean;
}

Configuring with environment variables

Environment variables have a higher priority than bunfig.toml.

bun always tries to use the fastest available installation method for the target platform. On macOS, that’s clonefile and on Linux, that’s hardlink. You can change which installation method is used with the --backend flag. When unavailable or on error, clonefile and hardlink fallsback to a platform-specific implementation of copying files.

bun stores installed packages from npm in ~/.bun/install/cache/${name}@${version}. Note that if the semver version has a build or a pre tag, it is replaced with a hash of that value instead. This is to reduce the chances of errors from long file paths, but unfortunately complicates figuring out where a package was installed on disk.

When the node_modules folder exists, before installing, bun checks if the "name" and "version" in package/package.json in the expected node_modules folder matches the expected name and version. This is how it determines whether it should install. It uses a custom JSON parser which stops parsing as soon as it finds "name" and "version".

When a bun.lockb doesn’t exist or package.json has changed dependencies, tarballs are downloaded & extracted eagerly while resolving.

When a bun.lockb exists and package.json hasn’t changed, bun downloads missing dependencies lazily. If the package with a matching name & version already exists in the expected location within node_modules, bun won’t attempt to download the tarball.

Platform-specific dependencies?

bun stores normalized cpu and os values from npm in the lockfile, along with the resolved packages. It skips downloading, extracting, and installing packages disabled for the current target at runtime. This means the lockfile won’t change between platforms/architectures even if the packages ultimately installed do change.

Peer dependencies?

Peer dependencies are handled similarly to yarn. bun install does not automatically install peer dependencies and will try to choose an existing dependency.

Lockfile

bun.lockb is bun’s binary lockfile format.

Why is it binary?

In a word: Performance. bun’s lockfile saves & loads incredibly quickly, and saves a lot more data than what is typically inside lockfiles.

How do I inspect it?

For now, the easiest thing is to run bun install -y. That prints a Yarn v1-style yarn.lock file.

What does the lockfile store?

Packages, metadata for those packages, the hoisted install order, dependencies for each package, what packages those dependencies resolved to, an integrity hash (if available), what each package was resolved to and which version (or equivalent).

Why is it fast?

It uses linear arrays for all data. Packages are referenced by an auto-incrementing integer ID or a hash of the package name. Strings longer than 8 characters are de-duplicated. Prior to saving on disk, the lockfile is garbage-collected & made deterministic by walking the package tree and cloning the packages in dependency order.

Cache

To delete the cache:

rm -rf ~/.bun/install/cache

Platform-specific backends

bun install uses different system calls to install dependencies depending on the platform. This is a performance optimization. You can force a specific backend with the --backend flag.

hardlink is the default backend on Linux. Benchmarking showed it to be the fastest on Linux.

rm -rf node_modules
bun install --backend hardlink

clonefile is the default backend on macOS. Benchmarking showed it to be the fastest on macOS. It is only available on macOS.

rm -rf node_modules
bun install --backend clonefile

clonefile_each_dir is similar to clonefile, except it clones each file individually per directory. It is only available on macOS and tends to perform slower than clonefile. Unlike clonefile, this does not recursively clone subdirectories in one system call.

rm -rf node_modules
bun install --backend clonefile_each_dir

copyfile is the fallback used when any of the above fail, and is the slowest. on macOS, it uses fcopyfile() and on linux it uses copy_file_range().

rm -rf node_modules
bun install --backend copyfile

symlink is typically only used for file: dependencies (and eventually link:) internally. To prevent infinite loops, it skips symlinking the node_modules folder.

If you install with --backend=symlink, Node.js won't resolve node_modules of dependencies unless each dependency has it's own node_modules folder or you pass --preserve-symlinks to node. See Node.js documentation on --preserve-symlinks.

rm -rf node_modules
bun install --backend symlink

# https://nodejs.org/api/cli.html#--preserve-symlinks
node --preserve-symlinks ./my-file.js

bun's runtime does not currently expose an equivalent of --preserve-symlinks, though the code for it does exist.

npm registry metadata

bun uses a binary format for caching NPM registry responses. This loads much faster than JSON and tends to be smaller on disk. You will see these files in ~/.bun/install/cache/*.npm. The filename pattern is ${hash(packageName)}.npm. It’s a hash so that extra directories don’t need to be created for scoped packages.

bun’s usage of Cache-Control ignores Age. This improves performance, but means bun may be about 5 minutes out of date to receive the latest package version metadata from npm.

bun run

bun run is a fast package.json script runner. Instead of waiting 170ms for your npm client to start every time, you wait 6ms for bun.

By default, bun run prints the script that will be invoked:

bun run clean
$ rm -rf node_modules/.cache dist

You can disable that with --silent

bun run --silent clean

bun run ${script-name} runs the equivalent of npm run script-name. For example, bun run dev runs the dev script in package.json, which may sometimes spin up non-bun processes.

bun run ${javascript-file.js} will run it with bun, as long as the file doesn't have a node shebang.

To print a list of scripts, bun run without additional args:

# This command
bun run

# Prints this
hello-create-react-app scripts:

bun run start
react-scripts start

bun run build
react-scripts build

bun run test
react-scripts test

bun run eject
react-scripts eject

4 scripts

bun run automatically loads environment variables from .env into the shell/task. .env files are loaded with the same priority as the rest of bun, so that means:

1. .env.local is first
2. if ($NODE_ENV === "production") .env.production else .env.development
3. .env

If something is unexpected there, you can run bun run env to get a list of environment variables.

The default shell it uses is bash, but if that’s not found, it tries sh and if still not found, it tries zsh. This is not configurable right now, but if you care, file an issue.

bun run automatically adds any parent node_modules/.bin to $PATH and if no scripts match, it will load that binary instead. That means you can run executables from packages, too.

# If you use Relay
bun run relay-compiler

# You can also do this, but:
# - It will only lookup packages in `node_modules/.bin` instead of `$PATH`
# - It will start bun’s dev server if the script name doesn’t exist (`bun` starts the dev server by default)
bun relay-compiler

To pass additional flags through to the task or executable, there are two ways:

# Explicit: include "--" and anything after will be added. This is the recommended way because it is more reliable.
bun run relay-compiler -- -–help

# Implicit: if you do not include "--", anything *after* the script name will be passed through
# bun flags are parsed first, which means e.g. `bun run relay-compiler --help` will print bun’s help instead of relay-compiler’s help.
bun run relay-compiler --schema foo.graphql

bun run supports lifecycle hooks like post${task} and pre{task}. If they exist, they will run, matching the behavior of npm clients. If the pre${task} fails, the next task will not be run. There is currently no flag to skip these lifecycle tasks if they exist, if you want that file an issue.

Run in Bun's JavaScript runtime

When given a JavaScript/TypeScript-like file, by default bun run will run it in Bun's JavaScript runtime.

With one caveat: if there's a #!/usr/bin/env node shebang, it will run it with Node.js instead by default.

To always run in Bun, use --bun:

bun run --bun my-script

This remaps node in $PATH for the duration of the task to bun so that anything trying to execute node will runs in Bun's JavaScript runtime instead.

bun --hot

bun --hot enables hot reloading of code in Bun's JavaScript runtime. This is a very experimental feature available in Bun v0.2.0.

Unlike file watchers like nodemon, bun --hot can keep stateful objects like the HTTP server running.

To use it with Bun's HTTP server (automatic):

server.ts:

// The global object is preserved across code reloads
// You can use it to store state, for now until Bun implements import.meta.hot.
const reloadCount = globalThis.reloadCount || 0;
globalThis.reloadCount = reloadCount + 1;

export default {
  fetch(req: Request) {
    return new Response(`Code reloaded ${reloadCount} times`, {
      headers: { "content-type": "text/plain" },
    });
  },
};

Then, run:

bun --hot server.ts

You can also use bun run:

bun run --hot server.ts

To use it manually:

// The global object is preserved across code reloads
// You can use it to store state, for now until Bun implements import.meta.hot.
const reloadCount = globalThis.reloadCount || 0;
globalThis.reloadCount = reloadCount + 1;

const reloadServer = (globalThis.reloadServer ||= (() => {
  let server;
  return (handler) => {
    if (server) {
      // call `server.reload` to reload the server
      server.reload(handler);
    } else {
      server = Bun.serve(handler);
    }
    return server;
  };
})());

const handler = {
  fetch(req: Request) {
    return new Response(`Code reloaded ${reloadCount} times`, {
      headers: { "content-type": "text/plain" },
    });
  },
};

reloadServer(handler);

In a future version of Bun, support for Vite's import.meta.hot is planned to enable better lifecycle management for hot reloading and to align with the ecosystem.

How bun --hot works

bun --hot monitors imported files for changes and reloads them. It does not monitor files that are not imported and it does not monitor node_modules.

On reload, it resets the internal require cache and ES module registry (Loader.registry).

Then:

• It runs the garbage collector synchronously (to minimize memory leaks, at the cost of runtime performance)
• Bun re-transpiles all of your code from scratch (including sourcemaps)
• JavaScriptCore (the engine) re-evaluates the code.

Traditional file watchers restart the entire process which means that HTTP servers and other stateful objects are lost. bun --hot does not restart the process, so it preserves some state across reloads to be less intrusive.

This implementation isn't particularly optimized. It re-transpiles files that haven't changed. It makes no attempt at incremental compilation. It's a starting point.

bun create

bun create is a fast way to create a new project from a template.

At the time of writing, bun create react app runs ~11x faster on my local computer than yarn create react-app app. bun create currently does no caching (though your npm client does)

Usage

Create a new Next.js project:

bun create next ./app

Create a new React project:

bun create react ./app

Create from a GitHub repo:

bun create ahfarmer/calculator ./app

To see a list of templates, run:

bun create

Format:

bun create github-user/repo-name destination
bun create local-example-or-remote-example destination
bun create /absolute/path/to-template-folder destination
bun create https://github.com/github-user/repo-name destination
bun create github.com/github-user/repo-name destination

Note: you don’t need bun create to use bun. You don’t need any configuration at all. This command exists to make it a little easier.

Local templates

If you have your own boilerplate you prefer using, copy it into $HOME/.bun-create/my-boilerplate-name.

Before checking bun’s templates on npmjs, bun create checks for a local folder matching the input in:

• $BUN_CREATE_DIR/
• $HOME/.bun-create/
• $(pwd)/.bun-create/

If a folder exists in any of those folders with the input, bun will use that instead of a remote template.

To create a local template, run:

mkdir -p $HOME/.bun-create/new-template-name
echo '{"name":"new-template-name"}' > $HOME/.bun-create/new-template-name/package.json

This lets you run:

bun create new-template-name ./app

Now your new template should appear when you run:

bun create

Warning: unlike with remote templates, bun will delete the entire destination folder if it already exists.

Flags

By default, bun create will cancel if there are existing files it would overwrite and it's a remote template. You can pass --force to disable this behavior.

Publishing a new template

Clone https://github.com/bun-community/create-templates/ and create a new folder in root directory with your new template. The package.json must have a name that starts with @bun-examples/. Do not worry about publishing it, that will happen automatically after the PR is merged.

Make sure to include a .gitignore that includes node_modules so that node_modules aren’t checked in to git when people download the template.

Testing your new template

To test your new template, add it as a local template or pass the absolute path.

bun create /path/to/my/new/template destination-dir

Warning: This will always delete everything in destination-dir.

Config

The bun-create section of package.json is automatically removed from the package.json on disk. This lets you add create-only steps without waiting for an extra package to install.

There are currently three options:

• postinstall
• preinstall
• start (customize the displayed start command)

They can be an array of strings or one string. An array of steps will be executed in order.

Here is an example:

{
  "name": "@bun-examples/next",
  "version": "0.0.31",
  "main": "index.js",
  "dependencies": {
    "next": "11.1.2",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "react-is": "^17.0.2"
  },
  "devDependencies": {
    "@types/react": "^17.0.19",
    "bun-framework-next": "^0.0.0-21",
    "typescript": "^4.3.5"
  },
  "bun-create": {
    "postinstall": ["bun bun --use next"],
    "start": "bun run echo 'Hello world!'"
  }
}

By default, all commands run inside the environment exposed by the auto-detected npm client. This incurs a significant performance penalty, something like 150ms spent waiting for the npm client to start on each invocation.

Any command that starts with "bun " will be run without npm, relying on the first bun binary in $PATH.

How bun create works

When you run bun create ${template} ${destination}, here’s what happens:

IF remote template

1. GET registry.npmjs.org/@bun-examples/${template}/latest and parse it

2. GET registry.npmjs.org/@bun-examples/${template}/-/${template}-${latestVersion}.tgz

3. Decompress & extract ${template}-${latestVersion}.tgz into ${destination}

   • If there are files that would overwrite, warn and exit unless --force is passed

IF GitHub repo

1. Download the tarball from GitHub’s API

2. Decompress & extract into ${destination}

   • If there are files that would overwrite, warn and exit unless --force is passed

ELSE IF local template

1. Open local template folder

2. Delete destination directory recursively

3. Copy files recursively using the fastest system calls available (on macOS fcopyfile and Linux, copy_file_range). Do not copy or traverse into node_modules folder if exists (this alone makes it faster than cp)

4. Parse the package.json (again!), update name to be ${basename(destination)}, remove the bun-create section from the package.json and save the updated package.json to disk.

   • IF Next.js is detected, add bun-framework-next to the list of dependencies
   • IF Create React App is detected, add the entry point in /src/index.{js,jsx,ts,tsx} to public/index.html
   • IF Relay is detected, add bun-macro-relay so that Relay works

5. Auto-detect the npm client, preferring pnpm, yarn (v1), and lastly npm

6. Run any tasks defined in "bun-create": { "preinstall" } with the npm client

7. Run ${npmClient} install unless --no-install is passed OR no dependencies are in package.json

8. Run any tasks defined in "bun-create": { "preinstall" } with the npm client

9. Run git init; git add -A .; git commit -am "Initial Commit";

   • Rename gitignore to .gitignore. NPM automatically removes .gitignore files from appearing in packages.
   • If there are dependencies, this runs in a separate thread concurrently while node_modules are being installed
   • Using libgit2 if available was tested and performed 3x slower in microbenchmarks

10. Done

misctools/publish-examples.js publishes all examples to npm.

bun bun

Run bun bun ./path-to.js to generate a node_modules.bun file containing all imported dependencies (recursively).

Why bundle?

• For browsers, loading entire apps without bundling dependencies is typically slow. With a fast bundler & transpiler, the bottleneck eventually becomes the web browser’s ability to run many network requests concurrently. There are many workarounds for this. <link rel="modulepreload">, HTTP/3, etc., but none are more effective than bundling. If you have reproducible evidence to the contrary, feel free to submit an issue. It would be better if bundling wasn’t necessary.
• On the server, bundling reduces the number of filesystem lookups to load JavaScript. While filesystem lookups are faster than HTTP requests, there’s still overhead.

What is .bun?

Note: This format may change soon

The .bun file contains:

• all the bundled source code
• all the bundled source code metadata
• project metadata & configuration

Here are some of the questions .bun files answer:

• when I import react/index.js, where in the .bun is the code for that? (not resolving, just the code)
• what modules of a package are used?
• what framework is used? (e.g., Next.js)
• where is the routes directory?
• how big is each imported dependency?
• what is the hash of the bundle’s contents? (for etags)
• what is the name & version of every npm package exported in this bundle?
• what modules from which packages are used in this project? ("project" is defined as all the entry points used to generate the .bun)

All in one file.

It’s a little like a build cache, but designed for reuse across builds.

Position-independent code

From a design perspective, the most important part of the .bun format is how code is organized. Each module is exported by a hash like this:

// preact/dist/preact.module.js
export var $eb6819b = $$m({
  "preact/dist/preact.module.js": (module, exports) => {
    let n, l, u, i, t, o, r, f, e = {}, c = [], s = /acit|ex(?:s|g|n|p|$)|rph|grid|ows|mnc|ntw|ine[ch]|zoo|^ord|itera/i;
    // ... rest of code

This makes bundled modules position-independent. In theory, one could import only the exact modules in-use without reparsing code and without generating a new bundle. One bundle can dynamically become many bundles comprising only the modules in use on the webpage. Thanks to the metadata with the byte offsets, a web server can send each module to browsers zero-copy using sendfile. bun itself is not quite this smart yet, but these optimizations would be useful in production and potentially very useful for React Server Components.

To see the schema inside, have a look at JavascriptBundleContainer. You can find JavaScript bindings to read the metadata in src/api/schema.js. This is not really an API yet. It’s missing the part where it gets the binary data from the bottom of the file. Someday, I want this to be usable by other tools too.

Where is the code?

.bun files are marked as executable.

To print out the code, run ./node_modules.bun in your terminal or run bun ./path-to-node_modules.bun.

Here is a copy-pastable example:

./node_modules.bun > node_modules.js

This works because every .bun file starts with this:

#!/usr/bin/env bun

To deploy to production with bun, you’ll want to get the code from the .bun file and stick that somewhere your web server can find it (or if you’re using Vercel or a Rails app, in a public folder).

Note that .bun is a binary file format, so just opening it in VSCode or vim might render strangely.

Advanced

By default, bun bun only bundles external dependencies that are imported or required in either app code or another external dependency. An "external dependency" is defined as, "A JavaScript-like file that has /node_modules/ in the resolved file path and a corresponding package.json".

To force bun to bundle packages which are not located in a node_modules folder (i.e., the final, resolved path following all symlinks), add a bun section to the root project’s package.json with alwaysBundle set to an array of package names to always bundle. Here’s an example:

{
  "name": "my-package-name-in-here",
  "bun": {
    "alwaysBundle": ["@mybigcompany/my-workspace-package"]
  }
}

Bundled dependencies are not eligible for Hot Module Reloading. The code is served to browsers & bun.js verbatim. But, in the future, it may be sectioned off into only parts of the bundle being used. That’s possible in the current version of the .bun file (so long as you know which files are necessary), but it’s not implemented yet. Longer-term, it will include all import and export of each module inside.

What is the module ID hash?

The $eb6819b hash used here:

export var $eb6819b = $$m({

Is generated like this:

1. Murmur3 32-bit hash of [email protected]. This is the hash uniquely identifying the npm package.
2. Wyhash 64 of the package.hash + package_path. package_path means "relative to the root of the npm package, where is the module imported?". For example, if you imported react/jsx-dev-runtime.js, the package_path is jsx-dev-runtime.js. react-dom/cjs/react-dom.development.js would be cjs/react-dom.development.js
3. Truncate the hash generated above to a u32

The implementation details of this module ID hash will vary between versions of bun. The important part is the metadata contains the module IDs, the package paths, and the package hashes, so it shouldn’t really matter in practice if other tooling wants to make use of any of this.

bun upgrade

To upgrade bun, run bun upgrade.

It automatically downloads the latest version of bun and overwrites the currently-running version.

This works by checking the latest version of bun in bun-releases-for-updater and unzipping it using the system-provided unzip library (so that Gatekeeper works on macOS)

If for any reason you run into issues, you can also use the curl install script:

curl https://bun.sh/install | bash

It will still work when bun is already installed.

bun is distributed as a single binary file, so you can also do this manually:

• Download the latest version of bun for your platform in bun-releases-for-updater (darwin == macOS)
• Unzip the folder
• Move the bun binary to ~/.bun/bin (or anywhere)

Canary builds

Canary builds are generated on every commit.

To install a canary build of bun, run:

bun upgrade --canary

This flag is not persistent (though that might change in the future). If you want to always run the canary build of bun, set the BUN_CANARY environment variable to 1 in your shell's startup script.

This will download the release zip from https://github.com/oven-sh/bun/releases/tag/canary.

To revert to the latest published version of bun, run:

bun upgrade

bun init

bun init is a quick way to start a blank project with Bun. It guesses with sane defaults and is non-destructive when run multiple times.

It creates:

• a package.json file with a name that defaults to the current directory name
• a tsconfig.json file or a jsconfig.json file, depending if the entry point is a TypeScript file or not
• an entry point which defaults to index.ts unless any of index.{tsx, jsx, js, mts, mjs} exist or the package.json specifies a module or main field
• a README.md file

If you pass -y or --yes, it will assume you want to continue without asking questions.

At the end, it runs bun install to install bun-types.

Added in Bun v0.1.7.

How is bun init different than bun create?

bun init is for blank projects. bun create applies templates.

bun completions

This command installs completions for zsh and/or fish. It runs automatically on every bun upgrade and on install. It reads from $SHELL to determine which shell to install for. It tries several common shell completion directories for your shell and OS.

If you want to copy the completions manually, run bun completions > path-to-file. If you know the completions directory to install them to, run bun completions /path/to/directory.

Loader API

Bun v0.1.11 introduces custom loaders.

• import and require .svelte, .vue, .yaml, .scss, .less and other file extensions that Bun doesn't implement a builtin loader for
• Dynamically generate ESM & CJS modules

YAML loader via js-yaml

This is an "object" loader. object loaders let you return a JS object that Bun converts to an ESM & CJS module.

Plugin implementation (my-yaml-plugin.js)

import { plugin } from "bun";

plugin({
  name: "YAML",

  setup(builder) {
    const { load } = require("js-yaml");
    const { readFileSync } = require("fs");
    // Run this function on any import that ends with .yaml or .yml
    builder.onLoad({ filter: /\.(yaml|yml)$/ }, (args) => {
      // Read the YAML file from disk
      const text = readFileSync(args.path, "utf8");

      // parse the YAML file with js-yaml
      const exports = load(text);

      return {
        // Copy the keys and values from the parsed YAML file into the ESM module namespace object
        exports,

        // we're returning an object
        loader: "object",
      };
    });
  },
});

Plugin usage:

import "./my-yaml-plugin.js";
import { hello } from "./myfile.yaml";

console.log(hello); // "world"

Svelte loader using svelte/compiler

This is a "js" loader, which lets you return a JS string or ArrayBufferView that Bun converts to an ESM & CJS module.

Plugin implementation (myplugin.js)

import { plugin } from "bun";

await plugin({
  name: "svelte loader",
  async setup(builder) {
    const { compile } = await import("svelte/compiler");
    const { readFileSync } = await import("fs");

    // Register a loader for .svelte files
    builder.onLoad({ filter: /\.svelte$/ }, ({ path }) => ({
      // Run the Svelte compiler on the import path
      contents: compile(readFileSync(path, "utf8"), {
        filename: path,
        generate: "ssr",
      }).js.code,

      // Set the loader to "js"
      // This runs it through Bun's transpiler
      loader: "js",
    }));
  },
});

Note: in a production implementation, you'd want to cache the compiled output and include additional error handling.

Plugin usage:

import "./myplugin.js";
import MySvelteComponent from "./component.svelte";

console.log(mySvelteComponent.render());

Loader API Reference

Bun's loader API interface is loosely based on esbuild. Some esbuild plugins "just work" in Bun.

MDX:

import { plugin } from "bun";
import { renderToStaticMarkup } from "react-dom/server";

// it's the esbuild plugin, but it works using Bun's transpiler.
import mdx from "@mdx-js/esbuild";

plugin(mdx());

import Foo from "./bar.mdx";
console.log(renderToStaticMarkup(<Foo />));

At the core of the loader API are filter and namespace. filter is a RegExp matched against import paths. namespace is a prefix inserted into the import path (unlike esbuild, Bun inserts the prefix into transpiled output). For example, if you have a loader with a filter of \.yaml$ and a namespace of yaml:, then the import path ./myfile.yaml will be transformed to yaml:./myfile.yaml.

plugin function

At the top-level, a plugin function exported from "bun" expects a "name" string and a "setup" function that takes a builder object.

For plugins to automatically activate, the plugin function must be from an import statement like this:

import { plugin } from "bun";

// This automatically activates on import
plugin({
  name: "my plugin",
  setup(builder) {},
});

/* Bun.plugin() does not automatically activate. */

Inside the setup function, you can:

• register loaders using builder.onLoad()
• register resolvers using builder.onResolve()

Internally, Bun's transpiler automatically turns plugin() calls into separate files (at most 1 per file). This lets loaders activate before the rest of your application runs with zero configuration.

builder.onLoad({ filter, namespace?: "optional-namespace" }, callback)

builder.onLoad() registers a loader for a matching filter RegExp and namespace string.

The callback function is called with an args object that contains the following properties:

• path: the path of the file being loaded

For now, that's the only property. More will likely be added in the future.

Loader types

There are different types of loaders:

• "js", "jsx", "ts", "tsx": these loaders run the source text through Bun's transpiler
• "json", "toml": these loaders run the source text through Bun's built-in parsers
• "object": this loader inserts a new ECMAScript Module into the ECMAScript Module registry by copying all the keys and values from the "exports" object into the Module Namespace Object

The callback function expects a return value that contains contents and loader properties, unless the loader is "object".

"contents" is the source code. It can be a string or an ArrayBufferView.

"loader" is the loader type. It can be "js", "jsx", "ts", "tsx", "json", "toml", or "object".

If "loader" is "object", the callback function expects a "exports" object instead of "contents". The keys and values will be copied onto the ESM module namespace object.

"object" loaders are useful when the return value is parsed into an object, like when parsing YAML, JSON, or other data formats. Most loader APIs force you to stringify values and parse again. This loader lets you skip that step, which improves performance and is a little easier sometimes.

Bun.serve - fast HTTP server

For a hello world HTTP server that writes "bun!", Bun.serve serves about 2.5x more requests per second than node.js on Linux:

^{Bigger is better}

Code

Bun:

Bun.serve({
  fetch(req: Request) {
    return new Response(`bun!`);
  },
  port: 3000,
});

Node:

require("http")
  .createServer((req, res) => res.end("bun!"))
  .listen(8080);

Usage

Two ways to start an HTTP server with bun.js:

1. export default an object with a fetch function

If the file used to start bun has a default export with a fetch function, it will start the HTTP server.

// hi.js
export default {
  fetch(req) {
    return new Response("HI!");
  },
};

// bun ./hi.js

fetch receives a Request object and must return either a Response or a Promise<Response>. In a future version, it might have additional arguments for things like cookies.

2. Bun.serve starts the HTTP server explicitly

Bun.serve({
  fetch(req) {
    return new Response("HI!");
  },
});

Error handling

For error handling, you get an error function.

If development: true and error is not defined or doesn't return a Response, you will get an exception page with a stack trace:

It will hopefully make it easier to debug issues with bun until bun gets debugger support. This error page is based on what bun dev does.

If the error function returns a Response, it will be served instead

Bun.serve({
  fetch(req) {
    throw new Error("woops!");
  },
  error(error: Error) {
    return new Response("Uh oh!!\n" + error.toString(), { status: 500 });
  },
});

If the error function itself throws and development is false, a generic 500 page will be shown

To stop the server, call server.stop():

const server = Bun.serve({
  fetch() {
    return new Response("HI!");
  },
});

server.stop();

HTTPS with Bun.serve()

Bun.serve() has builtin support for TLS (HTTPS). Pass keyFile and certFile option to enable HTTPS.

Example:

Bun.serve({
  fetch(req) {
    return new Response("Hello!!!");
  },
  /**
   * File path to a TLS key
   *
   * To enable TLS, this option is required.
   */
  keyFile: "./key.pem",
  /**
   * File path to a TLS certificate
   *
   * To enable TLS, this option is required.
   */
  certFile: "./cert.pem",

  /**
   * Optional SSL options
   */
  // passphrase?: string;
  // caFile?: string;
  // dhParamsFile?: string;
  // lowMemoryMode?: boolean;
});

Streaming files with Bun.serve()

Bun.serve() lets you stream files fast.

To stream a file, return a Response object with a Bun.file(pathOrFd) object as the body.

import { serve, file } from "bun";

serve({
  fetch(req) {
    return new Response(file("./hello.txt"));
  },
});

Bun automatically uses the sendfile(2) system call when possible, enabling zero-copy file transfers in the kernel — the fastest way to send files.

Note: You can also read the files into memory and send it manually, but that is slower.

Sending only part of a file

^{Available in Bun v0.3.0}

Bun.serve() has builtin support for the Content-Range header

To stream up to the first N bytes of a file, call slice(start, end) on the Bun.file object:

import { serve, file } from "bun";

serve({
  fetch(req) {
    const [start = 0, end = Infinity] =
      req.headers.get("Range").split("=").at(-1).split("-") ?? [];

    return new Response(
      file("./my-big-video-to-stream.mp4").slice(Number(start), Number(end)),
    );
  },
});

WebSockets with Bun.serve()

Bun.serve() has builtin support for server-side websockets (as of Bun v0.2.1).

Features:

• Compression (pass perMessageDeflate: true)
• HTTPS
• Pubsub / broadcast support with MQTT-like topics

It's also fast. For a chatroom on Linux x64:

Here is an example that echoes back any message it receives:

Bun.serve({
  websocket: {
    message(ws, message) {
      ws.send(message);
    },
  },

  fetch(req, server) {
    // Upgrade to a ServerWebSocket if we can
    // This automatically checks for the `Sec-WebSocket-Key` header
    // meaning you don't have to check headers, you can just call `upgrade()`
    if (server.upgrade(req))
      // When upgrading, we return undefined since we don't want to send a Response
      return;

    return new Response("Regular HTTP response");
  },
});

Here is a more complete example:

type User = {
  name: string;
};

Bun.serve<User>({
  fetch(req, server) {
    if (req.url === "/chat") {
      if (
        server.upgrade(req, {
          // This User object becomes ws.data
          data: {
            name: new URL(req.url).searchParams.get("name") || "Friend",
          },
          // Pass along some headers to the client
          headers: {
            "Set-Cookie": "name=" + new URL(req.url).searchParams.get("name"),
          },
        })
      )
        return;
    }

    return new Response("Expected a websocket connection", { status: 400 });
  },

  websocket: {
    open(ws) {
      console.log("WebSocket opened");

      // subscribe to "the-group-chat" topic
      ws.subscribe("the-group-chat");
    },

    message(ws, message) {
      // In a group chat, we want to broadcast to everyone
      // so we use publish()
      ws.publish("the-group-chat", `${ws.data.name}: ${message}`);
    },

    close(ws, code, reason) {
      ws.publish("the-group-chat", `${ws.data.name} left the chat`);
    },

    drain(ws) {
      console.log("Please send me data. I am ready to receive it.");
    },

    // enable compression
    perMessageDeflate: true,
    /*
    * perMessageDeflate: {
       **
       * Enable compression on the {@link ServerWebSocket}
       *
       * @default false
       *
       * `true` is equivalent to `"shared"
       compress?: WebSocketCompressor | false | true;
       **
       * Configure decompression
       *
       * @default false
       *
       * `true` is equivalent to `"shared"
       decompress?: WebSocketCompressor | false | true;
    */

    /**
     * The maximum size of a message
     */
    // maxPayloadLength?: number;
    /**
     * After a connection has not received a message for this many seconds, it will be closed.
     * @default 120 (2 minutes)
     */
    // idleTimeout?: number;
    /**
     * The maximum number of bytes that can be buffered for a single connection.
     * @default 16MB
     */
    // backpressureLimit?: number;
    /**
     * Close the connection if the backpressure limit is reached.
     * @default false
     */
    // closeOnBackpressureLimit?: boolean;

    // this makes it so ws.data shows up as a Request object
  },
  // TLS is also supported with WebSockets
  /**
   * File path to a TLS key
   *
   * To enable TLS, this option is required.
   */
  // keyFile: "./key.pem",
  /**
   * File path to a TLS certificate
   *
   * To enable TLS, this option is required.
   */
  // certFile: "./cert.pem",
});

ServerWebSocket vs WebSocket

For server websocket connections, Bun exposes a ServerWebSocket class which is similar to the web-standard WebSocket class used for websocket client connections, but with a few differences:

Headers

ServerWebSocket supports passing headers. This is useful for setting cookies or other headers that you want to send to the client before the connection is upgraded.

Bun.serve({
  fetch(req, server) {
    if (
      server.upgrade(req, { headers: { "Set-Cookie": "name=HiThereMyNameIs" } })
    )
      return;
  },
  websocket: {
    message(ws, message) {
      ws.send(message);
    },
  },
});

The web-standard WebSocket API does not let you specify headers.

Publish/subscribe

ServerWebSocket has publish(), subscribe(), and unsubscribe methods which let you broadcast the same message to all clients connected to a topic in one line of code.

ws.publish("stock-prices/GOOG", `${price}`);

Backpressure

ServerWebSocket.send returns a number that indicates:

• 0 if the message was dropped due to a connection issue
• -1 if the message was enqueued but there is backpressure
• any other number indicates the number of bytes sent

This lets you have better control over backpressure in your server.

You can also enable/disable compression per message with the compress option:

// this will compress
ws.send("Hello".repeat(1000), true);

WebSocket.send returns undefined and does not indicate backpressure, which can cause issues if you are sending a lot of data.

ServerWebSocket also supports a drain callback that runs when the connection is ready to receive more data.

Callbacks are per server instead of per socket

ServerWebSocket expects you to pass a WebSocketHandler object to the Bun.serve() method which has methods for open, message, close, drain, and error. This is different than the client-side WebSocket class which extends EventTarget (onmessage, onopen, onclose),

Clients tend to not have many socket connections open so an event-based API makes sense.

But servers tend to have many socket connections open, which means:

• Time spent adding/removing event listeners for each connection adds up
• Extra memory spent on storing references to callbacks function for each connection
• Usually, people create new functions for each connection, which also means more memory

So, instead of using an event-based API, ServerWebSocket expects you to pass a single object with methods for each event in Bun.serve() and it is reused for each connection.

This leads to less memory usage and less time spent adding/removing event listeners.

The interface for Bun.serve is loosely based on what Cloudflare Workers does.

The HTTP server and server-side websockets are based on uWebSockets.

Bun.spawn – spawn a process

Bun.spawn lets you quickly spawn a process. Available as of Bun v0.2.0.

import { spawn } from "bun";

const { stdout } = spawn(["esbuild"], {
  stdin: await fetch(
    "https://raw.githubusercontent.com/oven-sh/bun/main/examples/hashing.js",
  ),
});

const text = await new Response(stdout).text();
console.log(text); // "const input = "hello world".repeat(400); ..."

Bun.spawn spawns processes 60% faster than Node.js' child_process.

❯ bun spawn.mjs
cpu: Apple M1 Max
runtime: bun 0.2.0 (arm64-darwin)

benchmark              time (avg)             (min … max)       p75       p99      p995
--------------------------------------------------------- -----------------------------
spawnSync echo hi  888.14 µs/iter    (821.83 µs … 1.2 ms) 905.92 µs      1 ms   1.03 ms

❯ node spawn.node.mjs
cpu: Apple M1 Max
runtime: node v18.9.1 (arm64-darwin)

benchmark              time (avg)             (min … max)       p75       p99      p995
--------------------------------------------------------- -----------------------------
spawnSync echo hi    1.47 ms/iter     (1.14 ms … 2.64 ms)   1.57 ms   2.37 ms   2.52 ms

Synchronous example:

import { spawnSync } from "bun";

const { stdout } = spawnSync(["echo", "hi"]);

// When using spawnSync, stdout is a Buffer
// this lets you read from it synchronously
const text = stdout.toString();

console.log(text); // "hi\n"

You can pass an object as the second argument to customize the process:

import { spawn } from "bun";

const { stdout } = spawn(["printenv", "FOO"], {
  cwd: "/tmp",

  env: {
    ...process.env,
    FOO: "bar",
  },

  // Disable stdin
  stdin: null,

  // Allow us to read from stdout
  stdout: "pipe",

  // Point stderr to write to "/tmp/stderr.log"
  stderr: Bun.file("/tmp/stderr.log"),
});

const text = await new Response(stdout).text();
console.log(text); // "bar\n"

You can also pass a Bun.file for stdin:

import { spawn, file, write } from "bun";

await write("/tmp/foo.txt", "hi");
const { stdout } = spawn(["cat"], {
  // Set /tmp/foo.txt as stdin
  stdin: file("/tmp/foo.txt"),
});

const text = await new Response(stdout).text();
console.log(text); // "hi\n"

stdin also accepts a TypedArray:

import { spawn } from "bun";

const { stdout } = spawn(["cat"], {
  stdin: new TextEncoder().encode("hi"),
  stdout: "pipe",
});

const text = await new Response(stdout).text();
console.log(text); // "hi\n"

Bun.spawn also supports incrementally writing to stdin:

⚠️ This API is a little buggy right now

import { spawn } from "bun";

const { stdin, stdout } = spawn(["cat"], {
  stdin: "pipe",
  stdout: "pipe",
});

// You can pass it strings or TypedArrays
// Write "hi" to stdin
stdin.write("hi");

// By default, stdin is buffered so you need to call flush() to send it
stdin.flush(true);

// When you're done, call end()
stdin.end();

const text = await new Response(stdout).text();
console.log(text); // "hi\n"

Under the hood, Bun.spawn and Bun.spawnSync use posix_spawn(3).

stdin

stdin can be one of:

• Bun.file()
• null (no stdin)
• ArrayBufferView
• Response, Request with a buffered body or from fetch(). ReadableStream is not supported yet (TODO)
• number (file descriptor)
• "pipe" (default), which returns a FileSink for fast incremental writing
• "inherit" which will inherit the parent's stdin

stdout and stderr

stdout and stderr can be one of:

• Bun.file()
• null (disable)
• number (file descriptor)
• "pipe" (default for stdout), returns a ReadableStream
• "inherit" (default for stderr) which will inherit the parent's stdout/stderr

When to use Bun.spawn vs Bun.spawnSync

There are three main differences between Bun.spawn and Bun.spawnSync.

1. Bun.spawnSync blocks the event loop until the subprocess exits. For HTTP servers, you probably should avoid using Bun.spawnSync but for CLI apps, you probably should use Bun.spawnSync.

2. spawnSync returns a different object for stdout and stderr so you can read the data synchronously.

3. Bun.spawn supports incrementally writing to stdin.

If you need to read from stdout or stderr synchronously, you should use Bun.spawnSync. Otherwise, Bun.spawn is preferred.

More details

Bun.spawn returns a Subprocess object.

More complete types are available in bun-types.

interface Subprocess {
  readonly pid: number;
  readonly stdin: FileSink | undefined;
  readonly stdout: ReadableStream | number | undefined;
  readonly stderr: ReadableStream | number | undefined;

  readonly exitCode: number | undefined;

  // Wait for the process to exit
  readonly exited: Promise<number>;

  // Keep Bun's process alive until the subprocess exits
  ref(): void;

  // Don't keep Bun's process alive until the subprocess exits
  unref(): void;

  // Kill the process
  kill(code?: number): void;
  readonly killed: boolean;
}

Bun.which – find the path to a binary

Find the path to an executable, similar to typing which in your terminal.

const ls = Bun.which("ls");
console.log(ls); // "/usr/bin/ls"

Bun.which defaults the PATH to the current PATH environment variable, but you can customize it

const ls = Bun.which("ls", {
  PATH: "/usr/local/bin:/usr/bin:/bin",
});
console.log(ls); // "/usr/bin/ls"

Bun.which also accepts a cwd option to search for the binary in a specific directory.

const ls = Bun.which("ls", {
  cwd: "/tmp",
  PATH: "",
});

console.log(ls); // null

Bun.listen & Bun.connect - TCP/TLS sockets

Bun.listen and Bun.connect is bun's native TCP & TLS socket API. Use it to implement database clients, game servers – anything that needs to communicate over TCP (instead of HTTP). This is a low-level API intended for library authors and for advanced use cases.

Start a TCP server with Bun.listen:

// The server
Bun.listen({
  hostname: "localhost",
  port: 8080,
  socket: {
    open(socket) {
      socket.write("hello world");
    },
    data(socket, data) {
      console.log(data instanceof Uint8Array); // true
    },
    drain(socket) {
      console.log("gimme more data");
    },
    close(socket) {
      console.log("goodbye!");
    },
  },
  // This is a TLS socket
  // certFile: "/path/to/cert.pem",
  // keyFile: "/path/to/key.pem",
});

Bun.connect lets you create a TCP client:

// The client
Bun.connect({
  hostname: "localhost",
  port: 8080,

  socket: {
    open(socket) {
      socket.write("hello server, i'm the client!");
    },
    data(socket, message) {
      socket.write("thanks for the message! Sincerely, " + socket.data.name);
    },
    drain(socket) {
      console.log("my socket is ready for more data");
    },
    close(socket) {
      console.log("");
    },
    timeout(socket) {
      console.log("socket timed out");
    },
  },

  data: {
    name: "Clienty McClientface",
  },
});

Benchmark-driven API design

Bun's TCP socket API is designed to go fast.

Instead of using promises or assigning callbacks per socket instance (like Node.js' EventEmitter or the web-standard WebSocket API), assign all callbacks one time

This design decision was made after benchmarking. For performance-sensitive servers, promise-heavy APIs or assigning callbacks per socket instance can cause significant garbage collector pressure and increase memory usage. If you're using a TCP server API, you probably care more about performance.

Bun.listen({
  socket: {
    open(socket) {},
    data(socket, data) {},
    drain(socket) {},
    close(socket) {},
    error(socket, error) {},
  },
  hostname: "localhost",
  port: 8080,
});

Instead of having to allocate unique functions for each instance of a socket, we can use each callback once for all sockets. This is a small optimization, but it adds up.

How do you pass per-socket data to each socket object?

**data** is a property on the TCPSocket & TLSSocket object that you can use to store per-socket data.

socket.data = { name: "Clienty McClientface" };

You can assign a default value to data in the connect or listen options.

Bun.listen({
  socket: {
    open(socket) {
      console.log(socket.data); // { name: "Servery McServerface" }
    },
  },
  data: {
    name: "Servery McServerface",
  },
});

Hot-reloading TCP servers & clients

TCPSocket (returned by Bun.connect and passed through callbacks in Bun.listen) has a reload method that lets you reload the callbacks for all related sockets (either just the one for Bun.connect or all sockets for Bun.listen):

const socket = Bun.connect({
  hostname: "localhost",
  port: 8080,
  socket: {
    data(socket, msg) {
      console.log("wow i got a message!");

      // this will be called the next time the server sends a message
      socket.reload({
        data(socket) {
          console.log("okay, not so surprising this time");
        },
      });
    },
  },
});

No buffering

Currently, TCPSocket & TLSSocket in Bun do not buffer data. Adding support for corking (similar to ServerWebSocket) is planned, but it means you will need to handle backpressure yourself using the drain callback.

Your TCP client/server will have abysmal performance if you don't consider buffering carefully.

For example, this:

socket.write("h");
socket.write("e");
socket.write("l");
socket.write("l");
socket.write("o");

Performs significantly worse than:

socket.write("hello");

To simplify this for now, consider using ArrayBufferSink with the {stream: true} option:

const sink = new ArrayBufferSink({ stream: true, highWaterMark: 1024 });

sink.write("h");
sink.write("e");
sink.write("l");
sink.write("l");
sink.write("o");

queueMicrotask(() => {
  var data = sink.flush();
  if (!socket.write(data)) {
    // put it back in the sink if the socket is full
    sink.write(data);
  }
});

Builtin buffering is planned in a future version of Bun.

Bun.dns - lookup a domain

Bun.dns includes utilities to make DNS requests, similar to node:dns. As of Bun v0.5.0, the only implemented function is dns.lookup, though more will be implemented soon.

You can lookup the IP addresses of a hostname by using dns.lookup.

import { dns } from "bun";

const [{ address }] = await dns.lookup("example.com");
console.log(address); // "93.184.216.34"

If you need to limit IP addresses to either IPv4 or IPv6, you can specify the family as an option.

import { dns } from "bun";

const [{ address }] = await dns.lookup("example.com", { family: 6 });
console.log(address); // "2606:2800:220:1:248:1893:25c8:1946"

Bun supports three backends for DNS resolution:

• c-ares - This is the default on Linux, and it uses the c-ares library to perform DNS resolution.
• system - Uses the system's non-blocking DNS resolver, if available. Otherwise, falls back to getaddrinfo. This is the default on macOS, and the same as getaddrinfo on Linux.
• getaddrinfo - Uses the POSIX standard getaddrinfo function, which may cause performance issues under concurrent load.

You can choose a particular backend by specifying backend as an option.

import { dns } from "bun";

const [{ address, ttl }] = await dns.lookup("example.com", {
  backend: "c-ares",
});
console.log(address); // "93.184.216.34"
console.log(ttl); // 21237

Note: the ttl property is only accurate when the backend is c-ares. Otherwise, ttl will be 0.

This was added in Bun v0.5.0.

Bun.peek - read a promise without resolving it

Bun.peek is a utility function that lets you read a promise's result without await or .then, but only if the promise has already fulfilled or rejected.

This function was added in Bun v0.2.2.

import { peek } from "bun";

const promise = Promise.resolve("hi");

// no await!
const result = peek(promise);

console.log(result); // "hi"

Bun.peek is useful for performance-sensitive code that wants to reduce the number of extra microticks. It's an advanced API and you probably shouldn't use it unless you know what you're doing.

import { peek } from "bun";
import { expect, test } from "bun:test";

test("peek", () => {
  const promise = Promise.resolve(true);

  // no await necessary!
  expect(peek(promise)).toBe(true);

  // if we peek again, it returns the same value
  const again = peek(promise);
  expect(again).toBe(true);

  // if we peek a non-promise, it returns the value
  const value = peek(42);
  expect(value).toBe(42);

  // if we peek a pending promise, it returns the promise again
  const pending = new Promise(() => {});
  expect(peek(pending)).toBe(pending);

  // If we peek a rejected promise, it:
  // - returns the error
  // - does not mark the promise as handled
  const rejected = Promise.reject(
    new Error("Successfully tested promise rejection"),
  );
  expect(peek(rejected).message).toBe("Successfully tested promise rejection");
});

peek.status lets you read the status of a promise without resolving it.

import { peek } from "bun";
import { expect, test } from "bun:test";

test("peek.status", () => {
  const promise = Promise.resolve(true);
  expect(peek.status(promise)).toBe("fulfilled");

  const pending = new Promise(() => {});
  expect(peek.status(pending)).toBe("pending");

  const rejected = Promise.reject(new Error("oh nooo"));
  expect(peek.status(rejected)).toBe("rejected");
});

Bun.write – optimizing I/O

Bun.write lets you write, copy or pipe files automatically using the fastest system calls compatible with the input and platform.

interface Bun {
  write(
    destination: string | number | FileBlob,
    input: string | FileBlob | Blob | ArrayBufferView,
  ): Promise<number>;
}

All this complexity is handled by a single function.

// Write "Hello World" to output.txt
await Bun.write("output.txt", "Hello World");

// log a file to stdout
await Bun.write(Bun.stdout, Bun.file("input.txt"));

// write the HTTP response body to disk
await Bun.write("index.html", await fetch("http://example.com"));
// this does the same thing
await Bun.write(Bun.file("index.html"), await fetch("http://example.com"));

// copy input.txt to output.txt
await Bun.write("output.txt", Bun.file("input.txt"));

bun:sqlite (SQLite3 module)

bun:sqlite is a high-performance built-in SQLite3 module for bun.js.

• Simple, synchronous API (synchronous is faster)
• Transactions
• Binding named & positional parameters
• Prepared statements
• Automatic type conversions (BLOB becomes Uint8Array)
• toString() prints as SQL

Installation:

# there's nothing to install
# bun:sqlite is built-in to bun.js

Example:

import { Database } from "bun:sqlite";

const db = new Database("mydb.sqlite");
db.run(
  "CREATE TABLE IF NOT EXISTS foo (id INTEGER PRIMARY KEY AUTOINCREMENT, greeting TEXT)",
);
db.run("INSERT INTO foo (greeting) VALUES (?)", "Welcome to bun!");
db.run("INSERT INTO foo (greeting) VALUES (?)", "Hello World!");

// get the first row
db.query("SELECT * FROM foo").get();
// { id: 1, greeting: "Welcome to bun!" }

// get all rows
db.query("SELECT * FROM foo").all();
// [
//   { id: 1, greeting: "Welcome to bun!" },
//   { id: 2, greeting: "Hello World!" },
// ]

// get all rows matching a condition
db.query("SELECT * FROM foo WHERE greeting = ?").all("Welcome to bun!");
// [
//   { id: 1, greeting: "Welcome to bun!" },
// ]

// get first row matching a named condition
db.query("SELECT * FROM foo WHERE greeting = $greeting").get({
  $greeting: "Welcome to bun!",
});
// [
//   { id: 1, greeting: "Welcome to bun!" },
// ]

bun:sqlite Benchmark

Database: Northwind Traders.

This benchmark can be run from ./bench/sqlite.

Here are results from an M1 Pro (64GB) on macOS 12.3.1.

SELECT * FROM "Order"

SELECT * FROM "Product"

SELECT * FROM "OrderDetail"

In screenshot form (which has a different sorting order)

Getting started with bun:sqlite

bun:sqlite's API is loosely based on better-sqlite3, though the implementation is different.

bun:sqlite has two classes:

• class Database
• class Statement

Database

Calling new Database(filename) opens or creates the SQLite database.

constructor(
      filename: string,
      options?:
        | number
        | {
            /**
             * Open the database as read-only (no write operations, no create).
             *
             * Equivalent to {@link constants.SQLITE_OPEN_READONLY}
             */
            readonly?: boolean;
            /**
             * Allow creating a new database
             *
             * Equivalent to {@link constants.SQLITE_OPEN_CREATE}
             */
            create?: boolean;
            /**
             * Open the database as read-write
             *
             * Equivalent to {@link constants.SQLITE_OPEN_READWRITE}
             */
            readwrite?: boolean;
          }
    );

To open or create a SQLite3 database:

import { Database } from "bun:sqlite";

const db = new Database("mydb.sqlite");

Open an in-memory database:

import { Database } from "bun:sqlite";

// all of these do the same thing
let db = new Database(":memory:");
let db = new Database();
let db = new Database("");

Open read-write and throw if the database doesn't exist:

import { Database } from "bun:sqlite";
const db = new Database("mydb.sqlite", { readwrite: true });

Open read-only and throw if the database doesn't exist:

import { Database } from "bun:sqlite";
const db = new Database("mydb.sqlite", { readonly: true });

Open read-write, don't throw if new file:

import { Database } from "bun:sqlite";
const db = new Database("mydb.sqlite", { readonly: true, create: true });

Open a database from a Uint8Array:

import { Database } from "bun:sqlite";
import { readFileSync } from "fs";

// unlike passing a filepath, this will not persist any changes to disk
// it will be read-write but not persistent
const db = new Database(readFileSync("mydb.sqlite"));

Close a database:

let db = new Database();
db.close();

Note: close() is called automatically when the database is garbage collected. It is safe to call multiple times but has no effect after the first.

Database.prototype.query

query(sql) creates a Statement for the given SQL and caches it, but does not execute it.

class Database {
  query(sql: string): Statement;
}

query returns a Statement object.

It performs the same operation as Database.prototype.prepare, except:

• query caches the prepared statement in the Database object
• query doesn't bind parameters

This intended to make it easier for bun:sqlite to be fast by default. Calling .prepare compiles a SQLite query, which can take some time, so it's better to cache those a little.

You can bind parameters on any call to a statement.

import { Database } from "bun:sqlite";

// generate some data
let db = new Database();
db.run(
  "CREATE TABLE foo (id INTEGER PRIMARY KEY AUTOINCREMENT, greeting TEXT)",
);
db.run("INSERT INTO foo (greeting) VALUES ($greeting)", {
  $greeting: "Welcome to bun",
});

// get the query
const stmt = db.query("SELECT * FROM foo WHERE greeting = ?");

// run the query
stmt.all("Welcome to bun!");
stmt.get("Welcome to bun!");
stmt.run("Welcome to bun!");

Database.prototype.prepare

prepare(sql) creates a Statement for the given SQL, but does not execute it.

Unlike query(), this does not cache the compiled query.

import { Database } from "bun:sqlite";

// generate some data
let db = new Database();
db.run(
  "CREATE TABLE foo (id INTEGER PRIMARY KEY AUTOINCREMENT, greeting TEXT)",
);

// compile the prepared statement
const stmt = db.prepare("SELECT * FROM foo WHERE bar = ?");

// run the prepared statement
stmt.all("baz");

Internally, this calls sqlite3_prepare_v3.

Database.prototype.exec & Database.prototype.run

exec is for one-off executing a query which does not need to return anything. run is an alias.

class Database {
  // exec is an alias for run
  exec(sql: string, ...params: ParamsType): void;
  run(sql: string, ...params: ParamsType): void;
}

This is useful for things like

Creating a table:

import { Database } from "bun:sqlite";

let db = new Database();
db.exec(
  "CREATE TABLE foo (id INTEGER PRIMARY KEY AUTOINCREMENT, greeting TEXT)",
);

Inserting one row:

import { Database } from "bun:sqlite";

let db = new Database();
db.exec(
  "CREATE TABLE foo (id INTEGER PRIMARY KEY AUTOINCREMENT, greeting TEXT)",
);

// insert one row
db.exec("INSERT INTO foo (greeting) VALUES ($greeting)", {
  $greeting: "Welcome to bun",
});

For queries which aren't intended to be run multiple times, it should be faster to use exec() than prepare() or query() because it doesn't create a Statement object.

Internally, this function calls sqlite3_prepare, sqlite3_step, and sqlite3_finalize.

Database.prototype.transaction

Creates a function that always runs inside a transaction. When the function is invoked, it will begin a new transaction. When the function returns, the transaction will be committed. If an exception is thrown, the transaction will be rolled back (and the exception will propagate as usual).

// setup
import { Database } from "bun:sqlite";
const db = Database.open(":memory:");
db.exec(
  "CREATE TABLE cats (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT UNIQUE, age INTEGER)",
);

const insert = db.prepare("INSERT INTO cats (name, age) VALUES ($name, $age)");
const insertMany = db.transaction((cats) => {
  for (const cat of cats) insert.run(cat);
});

insertMany([
  { $name: "Joey", $age: 2 },
  { $name: "Sally", $age: 4 },
  { $name: "Junior", $age: 1 },
]);

Transaction functions can be called from inside other transaction functions. When doing so, the inner transaction becomes a savepoint.

// setup
import { Database } from "bun:sqlite";
const db = Database.open(":memory:");
db.exec(
  "CREATE TABLE expenses (id INTEGER PRIMARY KEY AUTOINCREMENT, note TEXT, dollars INTEGER);",
);
db.exec(
  "CREATE TABLE cats (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT UNIQUE, age INTEGER)",
);
const newExpense = db.prepare(
  "INSERT INTO expenses (note, dollars) VALUES (?, ?)",
);
const insert = db.prepare("INSERT INTO cats (name, age) VALUES ($name, $age)");
const insertMany = db.transaction((cats) => {
  for (const cat of cats) insert.run(cat);
});

const adopt = db.transaction((cats) => {
  newExpense.run("adoption fees", 20);
  insertMany(cats); // nested transaction
});

adopt([
  { $name: "Joey", $age: 2 },
  { $name: "Sally", $age: 4 },
  { $name: "Junior", $age: 1 },
]);

Transactions also come with deferred, immediate, and exclusive versions.

insertMany(cats); // uses "BEGIN"
insertMany.deferred(cats); // uses "BEGIN DEFERRED"
insertMany.immediate(cats); // uses "BEGIN IMMEDIATE"
insertMany.exclusive(cats); // uses "BEGIN EXCLUSIVE"

Any arguments passed to the transaction function will be forwarded to the wrapped function, and any values returned from the wrapped function will be returned from the transaction function. The wrapped function will also have access to the same binding as the transaction function.

bun:sqlite's transaction implementation is based on better-sqlite3 (along with this section of the docs), so thanks to Joshua Wise and better-sqlite3 contributors.

Database.prototype.serialize

SQLite has a built-in way to serialize and deserialize databases to and from memory.

bun:sqlite fully supports it:

let db = new Database();

// write some data
db.run(
  "CREATE TABLE foo (id INTEGER PRIMARY KEY AUTOINCREMENT, greeting TEXT)",
);
db.run("INSERT INTO foo VALUES (?)", "Welcome to bun!");
db.run("INSERT INTO foo VALUES (?)", "Hello World!");

const copy = db.serialize();
// => Uint8Array

const db2 = new Database(copy);
db2.query("SELECT * FROM foo").all();
// => [
//   { id: 1, greeting: "Welcome to bun!" },
//   { id: 2, greeting: "Hello World!" },
// ]

db.serialize() returns a Uint8Array of the database.

Internally, it calls sqlite3_serialize.

Database.prototype.loadExtension

bun:sqlite supports SQLite extensions.

To load a SQLite extension, call Database.prototype.loadExtension(name):

import { Database } from "bun:sqlite";

let db = new Database();

db.loadExtension("myext");

If you're on macOS, you will need to first use a custom SQLite install (you can install with homebrew). By default, bun uses Apple's proprietary build of SQLite because it benchmarks about 50% faster. However, they disabled extension support, so you will need to have a custom build of SQLite to use extensions on macOS.

import { Database } from "bun:sqlite";

// on macOS, this must be run before any other calls to `Database`
// if called on linux, it will return true and do nothing
// on linux it will still check that a string was passed
Database.setCustomSQLite("/path/to/sqlite.dylib");

let db = new Database();

db.loadExtension("myext");

To install sqlite with homebrew:

brew install sqlite

Statement

Statement is a prepared statement. Use it to run queries that get results.

TLDR:

• Statement.all(...optionalParamsToBind) returns all rows as an array of objects
• Statement.values(...optionalParamsToBind) returns all rows as an array of arrays
• Statement.get(...optionalParamsToBind) returns the first row as an object
• Statement.run(...optionalParamsToBind) runs the statement and returns nothing
• Statement.finalize() closes the statement
• Statement.toString() prints the expanded SQL, including bound parameters
• get Statement.columnNames get the returned column names
• get Statement.paramsCount how many parameters are expected?

You can bind parameters on any call to a statement. Named parameters and positional parameters are supported. Bound parameters are remembered between calls and reset the next time you pass parameters to bind.

import { Database } from "bun:sqlite";

// setup
let db = new Database();
db.run(
  "CREATE TABLE foo (id INTEGER PRIMARY KEY AUTOINCREMENT, greeting TEXT)",
);
db.run("INSERT INTO foo VALUES (?)", "Welcome to bun!");
db.run("INSERT INTO foo VALUES (?)", "Hello World!");

// Statement object
let statement = db.query("SELECT * FROM foo");

// returns all the rows
statement.all();

// returns the first row
statement.get();

// runs the query, without returning anything
statement.run();

Statement.all