bun.sh/README.md

Bun

Documentation   •   Discord   •   Issues   •   Roadmap

Read the docs →

What is Bun?

Bun is under active development. Use it to speed up your development workflows or run simpler production code in resource-constrained environments like serverless functions. We're working on more complete Node.js compatibility and integration with existing frameworks. Join the Discord and watch the GitHub repository to keep tabs on future releases.

Bun is an all-in-one toolkit for JavaScript and TypeScript apps. It ships as a single executable called bun.

At its core is the Bun runtime, a fast JavaScript runtime designed as a drop-in replacement for Node.js. It's written in Zig and powered by JavaScriptCore under the hood, dramatically reducing startup times and memory usage.

bun run index.tsx             # TS and JSX supported out-of-the-box

The bun command-line tool also implements a test runner, script runner, and Node.js-compatible package manager. Instead of 1,000 node_modules for development, you only need bun. Bun's built-in tools are significantly faster than existing options and usable in existing Node.js projects with little to no changes.

bun test                      # run tests
bun run start                 # run the `start` script in `package.json`
bun install <pkg>             # install a package
bunx cowsay 'Hello, world!'   # execute a package

Install

Bun supports Linux (x64 & arm64), macOS (x64 & Apple Silicon) and Windows (x64).

Linux users — Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1.

# with install script (recommended)
curl -fsSL https://bun.sh/install | bash

# on windows
powershell -c "irm bun.sh/install.ps1 | iex"

# with npm
npm install -g bun

# with Homebrew
brew tap oven-sh/bun
brew install bun

# with Docker
docker pull oven/bun
docker run --rm --init --ulimit memlock=-1:-1 oven/bun

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

Quick links

• Intro

  • What is Bun?
  • Installation
  • Quickstart
  • TypeScript

• Templating

  • bun init
  • bun create

• Runtime

  • bun run
  • File types
  • TypeScript
  • JSX
  • Environment variables
  • Bun APIs
  • Web APIs
  • Node.js compatibility
  • Single-file executable
  • Plugins
  • Watch mode
  • Module resolution
  • Auto-install
  • bunfig.toml
  • Debugger
  • Framework API

• Package manager

  • bun install
  • bun add
  • bun remove
  • bun update
  • bun link
  • bun pm
  • Global cache
  • Workspaces
  • Lifecycle scripts
  • Filter
  • Lockfile
  • Scopes and registries
  • Overrides and resolutions

• Bundler

  • Bun.build
  • Loaders
  • Plugins
  • Macros
  • vs esbuild

• Test runner

  • bun test
  • Writing tests
  • Watch mode
  • Lifecycle hooks
  • Mocks
  • Snapshots
  • Dates and times
  • DOM testing
  • Code coverage

• Package runner

  • bunx

• API

  • HTTP server
  • WebSockets
  • Workers
  • Binary data
  • Streams
  • File I/O
  • import.meta
  • SQLite
  • FileSystemRouter
  • TCP sockets
  • UDP sockets
  • Globals
  • $ Shell
  • Child processes
  • Transpiler
  • Hashing
  • Console
  • FFI
  • HTMLRewriter
  • Testing
  • Utils
  • Node-API
  • Glob
  • Semver

• Project

  • Roadmap
  • Benchmarking
  • Contributing
  • Building Windows
  • License

Guides

• Binary

  • Convert an ArrayBuffer to an array of numbers
  • Convert an ArrayBuffer to a Blob
  • Convert an ArrayBuffer to a Buffer
  • Convert an ArrayBuffer to a string
  • Convert an ArrayBuffer to a Uint8Array
  • Convert a Blob to an ArrayBuffer
  • Convert a Blob to a DataView
  • Convert a Blob to a ReadableStream
  • Convert a Blob to a string
  • Convert a Blob to a Uint8Array
  • Convert a Buffer to an ArrayBuffer
  • Convert a Buffer to a blob
  • Convert a Buffer to a ReadableStream
  • Convert a Buffer to a string
  • Convert a Buffer to a Uint8Array
  • Convert a DataView to a string
  • Convert a Uint8Array to an ArrayBuffer
  • Convert a Uint8Array to a Blob
  • Convert a Uint8Array to a Buffer
  • Convert a Uint8Array to a DataView
  • Convert a Uint8Array to a ReadableStream
  • Convert a Uint8Array to a string

• Ecosystem

  • Build an app with Astro and Bun
  • Create a Discord bot
  • Containerize a Bun application with Docker
  • Use Drizzle ORM with Bun
  • Use EdgeDB with Bun
  • Build an HTTP server using Elysia and Bun
  • Build an HTTP server using Express and Bun
  • Build an HTTP server using Hono and Bun
  • Read and write data to MongoDB using Mongoose and Bun
  • Use Neon's Serverless Postgres with Bun
  • Build an app with Next.js and Bun
  • Build an app with Nuxt and Bun
  • Run Bun as a daemon with PM2
  • Use Prisma with Bun
  • Build an app with Qwik and Bun
  • Use React and JSX
  • Build an app with Remix and Bun
  • Build an app with SolidStart and Bun
  • Server-side render (SSR) a React component
  • Build an HTTP server using StricJS and Bun
  • Build an app with SvelteKit and Bun
  • Run Bun as a daemon with systemd
  • Build a frontend using Vite and Bun

• HTTP

  • fetch with unix domain sockets in Bun
  • Send an HTTP request using fetch
  • Upload files via HTTP using FormData
  • Hot reload an HTTP server
  • Proxy HTTP requests using fetch()
  • Common HTTP server usage
  • Write a simple HTTP server
  • Stream a file as an HTTP Response
  • Streaming HTTP Server with Async Iterators
  • Streaming HTTP Server with Node.js Streams
  • Configure TLS on an HTTP server

• Install

  • Add a development dependency
  • Add a Git dependency
  • Add an optional dependency
  • Add a peer dependency
  • Add a tarball dependency
  • Add a dependency
  • Using bun install with an Azure Artifacts npm registry
  • Install dependencies with Bun in GitHub Actions
  • Override the default npm registry for bun install
  • Configure git to diff Bun's lockb lockfile
  • Using bun install with Artifactory
  • Install a package under a different name
  • Configure a private registry for an organization scope with bun install
  • Add a trusted dependency
  • Configuring a monorepo using workspaces
  • Generate a human-readable lockfile

• Process

  • Parse command-line arguments
  • Listen for CTRL+C
  • Spawn a child process and communicate using IPC
  • Get the process uptime in nanoseconds
  • Listen to OS signals
  • Read stderr from a child process
  • Read stdout from a child process
  • Spawn a child process
  • Read from stdin

• Read file

  • Read a file to an ArrayBuffer
  • Read a file to a Buffer
  • Check if a file exists
  • Read a JSON file
  • Get the MIME type of a file
  • Read a file as a ReadableStream
  • Read a file as a string
  • Read a file to a Uint8Array
  • Watch a directory for changes

• Runtime

  • Install and run Bun in GitHub Actions
  • Define and replace static globals & constants
  • Import HTML file as text
  • Import a JSON file
  • Import a TOML file
  • Read environment variables
  • Set environment variables
  • Run a Shell Command
  • Set a time zone in Bun
  • Re-map import paths
  • Install TypeScript declarations for Bun
  • Debugging Bun with the VS Code extension
  • Debugging Bun with the web debugger

• Streams

  • Convert a Node.js Readable to an ArrayBuffer
  • Convert a Node.js Readable to a Blob
  • Convert a Node.js Readable to JSON
  • Convert a Node.js Readable to a string
  • Convert a ReadableStream to an array of chunks
  • Convert a ReadableStream to an ArrayBuffer
  • Convert a ReadableStream to a Blob
  • Convert a ReadableStream to a Buffer
  • Convert a ReadableStream to JSON
  • Convert a ReadableStream to a string
  • Convert a ReadableStream to a Uint8Array

• Test

  • Bail early with the Bun test runner
  • Set a code coverage threshold with the Bun test runner
  • Generate code coverage reports with the Bun test runner
  • Write browser DOM tests with Bun and happy-dom
  • Migrate from Jest to Bun's test runner
  • Set the system time in Bun's test runner
  • Mock functions in bun test
  • Re-run tests multiple times with the Bun test runner
  • Run your tests with the Bun test runner
  • Skip tests with the Bun test runner
  • Use snapshot testing in bun test
  • Spy on methods in bun test
  • Set a per-test timeout with the Bun test runner
  • Mark a test as a "todo" with the Bun test runner
  • Update snapshots in bun test
  • Run tests in watch mode with Bun

• Util

  • Encode and decode base64 strings
  • Check if two objects are deeply equal
  • Compress and decompress data with DEFLATE
  • Detect when code is executed with Bun
  • Check if the current file is the entrypoint
  • Escape an HTML string
  • Convert a file URL to an absolute path
  • Compress and decompress data with gzip
  • Hash a password
  • Get the directory of the current file
  • Get the file name of the current file
  • Get the absolute path of the current file
  • Get the absolute path to the current entrypoint
  • Convert an absolute path to a file URL
  • Sleep for a fixed number of milliseconds
  • Get the current Bun version
  • Get the path to an executable bin file

• WebSocket

  • Enable compression for WebSocket messages
  • Set per-socket contextual data on a WebSocket
  • Build a publish-subscribe WebSocket server
  • Build a simple WebSocket server

• Write file

  • Append content to a file
  • Write a string to a file
  • Write a Blob to a file
  • Write a file to stdout
  • Copy a file to another location
  • Write a file incrementally
  • Write a Response to a file
  • Write to stdout
  • Write a ReadableStream to a file
  • Delete a file

Contributing

Refer to the Project > Contributing guide to start contributing to Bun.

License

Refer to the Project > License page for information about Bun's licensing.