Bun

 

Incredibly fast JavaScript runtime, bundler, test runner, and nodejs package manager – all in one

bun.com

Documentation   •   Discord   •   Issues   •   Roadmap

Read the docs →

What is Bun?

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 Rust 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 & arm64).

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

x64 users — if you see "illegal instruction" or similar errors, check our CPU requirements

# with install script (recommended)
curl -fsSL https://bun.com/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
  • TypeScript 6

• Templating

  • bun init
  • bun create

• Runtime

  • bun run
  • File types (Loaders)
  • JSX
  • Environment variables
  • Bun APIs
  • Web APIs
  • Node.js compatibility
  • Plugins
  • Watch mode / Hot Reloading
  • Module resolution
  • Auto-install
  • bunfig.toml
  • Debugger
  • REPL
  • $ Shell

• Package manager

  • bun install
  • bun add
  • bun remove
  • bun update
  • bun link
  • bun pm
  • bun outdated
  • bun publish
  • bun patch
  • bun why
  • bun audit
  • bun info
  • Global cache
  • Global store
  • Isolated installs
  • Workspaces
  • Catalogs
  • Lifecycle scripts
  • Filter
  • Lockfile
  • Scopes and registries
  • Overrides and resolutions
  • Security scanner API
  • .npmrc

• Bundler

  • Bun.build
  • Loaders
  • Plugins
  • Macros
  • vs esbuild
  • Single-file executable
  • CSS
  • HTML & static sites
  • Hot Module Replacement (HMR)
  • Full-stack with HTML imports
  • Standalone HTML
  • Bytecode caching
  • Minifier

• Test runner

  • bun test
  • Writing tests
  • Lifecycle hooks
  • Mocks
  • Snapshots
  • Dates and times
  • DOM testing
  • Code coverage
  • Configuration
  • Discovery
  • Reporters
  • Runtime Behavior

• Package runner

  • bunx

• API

  • HTTP server (Bun.serve)
  • HTTP routing
  • HTTP error handling
  • HTTP metrics
  • WebSockets
  • Workers
  • Binary data
  • Streams
  • File I/O (Bun.file)
  • Archive (tar)
  • SQLite (bun:sqlite)
  • PostgreSQL (Bun.sql)
  • Redis (Bun.redis)
  • S3 Client (Bun.s3)
  • FileSystemRouter
  • TCP sockets
  • UDP sockets
  • Globals
  • Child processes (spawn)
  • Cron (Bun.cron)
  • WebView
  • Transpiler (Bun.Transpiler)
  • Hashing
  • Colors (Bun.color)
  • Console
  • FFI (bun:ffi)
  • C Compiler (bun:ffi cc)
  • HTMLRewriter
  • Cookies (Bun.Cookie)
  • CSRF (Bun.CSRF)
  • Secrets (Bun.secrets)
  • YAML (Bun.YAML)
  • TOML (Bun.TOML)
  • JSON5
  • JSONL
  • Markdown
  • Image processing
  • Utils
  • Node-API
  • Glob (Bun.Glob)
  • Semver (Bun.semver)
  • DNS
  • fetch API extensions

Guides

• Deployment

  • Deploy to Vercel
  • Deploy to Railway
  • Deploy to Render
  • Deploy to AWS Lambda
  • Deploy to DigitalOcean
  • Deploy to Google Cloud Run

• Binary

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

• Ecosystem

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

• HTMLRewriter

  • Extract links from a webpage using HTMLRewriter
  • Extract social share images and Open Graph tags

• HTTP

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

• Install

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

• Process

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

• Read file

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

• Runtime

  • Delete files
  • Run a Shell Command
  • Import a JSON file
  • Import a TOML file
  • Import a YAML file
  • Import a JSON5 file
  • Set a time zone in Bun
  • Set environment variables
  • Re-map import paths
  • Delete directories
  • Read environment variables
  • Import a HTML file as text
  • Install and run Bun in GitHub Actions
  • Debugging Bun with the web debugger
  • Install TypeScript declarations for Bun
  • Debugging Bun with the VS Code extension
  • Inspect memory usage using V8 heap snapshots
  • Define and replace static globals & constants
  • Build-time constants with --define
  • Codesign a single-file JavaScript executable on macOS

• Streams

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

• Test

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

• Util

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

• WebSocket

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

• Write file

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

  from https://github.com/oven-sh/bun 

  ----------------------------------------------------------

   

  Deploy a Bun application on Railway

  Deploy a Bun application to Railway from the CLI or dashboard, with optional PostgreSQL setup and automatic SSL

  Railway is an infrastructure platform: you provision infrastructure, develop against it locally, then deploy to the cloud. Railway deploys from GitHub with zero configuration, handles SSL automatically, and provisions databases.

  This guide deploys a Bun application with an optional PostgreSQL database, the same setup the following template provides.

  You can either follow this guide step-by-step or deploy the pre-configured template with one click:

  

  ---

  Prerequisites:

  • A Bun application ready for deployment
  • A Railway account
  • Railway CLI (for CLI deployment method)
  • A GitHub account (for Dashboard deployment method)

  ---

  Method 1: Deploy via CLI#

  Step 1

  Install the Railway CLI.

  terminal

  bun install -g @railway/cli

  Step 2

  Log into your Railway account.

  terminal

  railway login

  Step 3

  After authenticating, initialize a new project.

  terminal

  railway init

  Step 4

  After initializing the project, add a new database and service.

  Step 4 is only necessary if your application uses a database. If you don't need PostgreSQL, skip to Step 5.

  terminal

  # Add PostgreSQL database. Make sure to add this first!
  railway add --database postgres
  
  # Add your application service.
  railway add --service bun-react-db --variables DATABASE_URL=\${{Postgres.DATABASE_URL}}

  Step 5

  After creating and connecting the services, deploy the application to Railway. By default, services are only accessible within Railway's private network, so generate a public domain to make your app publicly accessible.

  # Deploy your application
  railway up
  
  # Generate public domain
  railway domain

  Your app is now live. railway up deploys your local directory rather than a GitHub repository. To have Railway auto-deploy on every GitHub push, connect the service to your repository with railway service source connect --repo <owner>/<repo> --branch <branch>.

  ---

  Method 2: Deploy via Dashboard#

  Step 1

  Create a new project

  1. Go to Railway Dashboard
  2. Click "+ New" → "GitHub repo"
  3. Choose your repository

  Step 2

  Add a PostgreSQL database, and connect this database to the serviceStep 2 is only necessary if your application uses a database. If you don't need PostgreSQL, skip to Step 3.

  1. Click "+ New" → "Database" → "Add PostgreSQL"
  2. After Railway creates the database, select your service (not the database)
  3. Go to "Variables" tab
  4. Click "+ New Variable" → "Add Reference"
  5. Select DATABASE_URL from postgres

  Step 3

  Generate a public domain

  1. Select your service
  2. Go to "Settings" tab
  3. Under "Networking", click "Generate Domain"

  Your app is now live. Railway auto-deploys on every GitHub push.

  ---

  Configuration (Optional)#

  By default, Railway uses Railpack to automatically detect and build your Bun application with zero configuration.

  Railpack detects Bun from your bun.lock and installs the latest version of Bun unless you pin one with the engines.bun or packageManager field in package.json. Railway's previous builder, Nixpacks, is in maintenance mode.

  If your service still builds with Nixpacks, switch it to Railpack by adding the following to your railway.json:railway.json

  {
    "$schema": "https://railway.com/railway.schema.json",
    "build": {
      "builder": "RAILPACK"
    }
  }

  For more build configuration settings, see the Railway documentation.

  from  https://bun.com/guides/deployment/railway