The Bun JavaScript runtime has rocketed past the 105,000-star mark on GitHub and now powers an estimated 28% of new JavaScript projects started on the platform in Q1 2026, according to MuchSkills’ developer survey. Built in Zig and engineered around Apple’s JavaScriptCore engine instead of Google’s V8, Bun fuses a runtime, bundler, package manager, and test runner into a single 40 MB binary that boots APIs in roughly 1.2 milliseconds, around 37 times faster than Node.js cold starts on the same hardware.

This Bun JavaScript tutorial walks you end-to-end through Bun 1.3, released February 2026, by building a complete production-ready REST API with persistent SQLite storage, JWT authentication, automated tests, and a Docker deployment pipeline. By the end of these 13 steps you will have a working repository that handles 1 million requests per second on a single core, ships as a 60 MB self-contained executable, and runs on Linux, macOS, and Windows without a separate Node.js install.

Updated April 04, 2026, this guide assumes you have written at least a few lines of JavaScript or TypeScript before. We will not paste a wall of theory; every section ends with a runnable code block, an expected output, and a pitfall the Bun core team and the wider community have hit on the path to 1.3. If you have followed our FastAPI REST API tutorial or our Next.js App Router walkthrough, the structure here will feel familiar.

Why Bun JavaScript Matters in 2026

Bun is no longer a curiosity. The runtime hit a stable 1.0 release in March 2025, then shipped 1.1 (July 2025), 1.2 (November 2025), and 1.3 (February 2026) on a roughly four-month cadence. Each release closed a significant gap with Node.js and added features that pure runtimes simply do not ship: a built-in TypeScript transformer with no tsc required, a Jest-compatible test runner that reads describe/it blocks natively, an esbuild-class bundler exposed as bun build, and a package manager that resolves and links the average node_modules tree five times faster than npm 11 in published benchmarks.

The numbers behind that adoption story matter. Per the official Bun documentation and TechEmpower Round 25 results published in Q1 2026, Bun’s HTTP server pushes more than 1 million plaintext requests per second per core, around 2.5 times the throughput of Express on Node.js 22 and roughly three times the throughput of Go’s Gin framework on the same VM. Memory usage is similarly tight: holding 10,000 concurrent WebSocket connections costs about 35 MB of resident memory in Bun versus around 250 MB in Node, according to LinearB’s 2026 observability report cited by Vercel. Vercel itself certified the Bun runtime on its Edge platform in late 2025, and roughly 20% of new Next.js production deploys on Vercel ran on Bun by April 2026.

The trade-off, which we cover honestly throughout this Bun JavaScript tutorial, is ecosystem maturity. Bun targets 95% npm compatibility, but a stubborn long tail of native-binding packages still misbehaves, and a handful of Node-specific debug tooling does not yet attach. We will flag every known compatibility gap as we hit it.

Bun 1.3 at a Glance: Versions, Features, Benchmarks

Before installing anything, it helps to know what each Bun release actually changed and which version powers the workflow you are about to build. Every command in this tutorial is verified against Bun 1.3.x. Older 1.0 and 1.1 versions will still run most of the code, but the native TypeScript decorator transform and the new Bun.SQL Postgres driver land in 1.3 and have no straightforward backport.

Bun Version	Released	Key Feature	Verified Benchmark	Status
Bun 1.0	March 2025	Stable runtime, bundler, test runner, package manager unified	1.2 ms cold start	Legacy
Bun 1.1	July 2025	Native WebSocket and Server-Sent Events	60% lower latency vs Node 22	Legacy
Bun 1.2	November 2025	Bun.serve() with HTTP/3 QUIC	2.5x throughput vs Express	Maintained
Bun 1.3	February 2026	Native TS transforms, Bun.SQL Postgres driver	80% faster builds vs esbuild + tsc	Current stable
Bun 1.4 (canary)	Q2 2026 (planned)	Worker threads parity, native fetch keepalive pool	Pending publication	Preview only

If you are weighing Bun against alternatives before you commit, the comparison table below summarises the headline numbers from official documentation and the TechEmpower Round 25 benchmark suite published in Q1 2026.

Metric	Bun 1.3	Node.js 22 LTS	Deno 2.x
Engine	JavaScriptCore	V8	V8
Cold start	1.2 ms	45 ms	15 ms
Plaintext req/sec/core	~1,000,000	~400,000	~600,000
Install speed (10k deps)	~5x faster than npm 11	baseline	~2x faster
Built-in test runner	Yes (Jest API)	node:test	Deno.test
Built-in bundler	Yes (bun build)	No	deno bundle (deprecated)
Built-in TypeScript	Yes (no tsc)	No (loader required)	Yes
Built-in SQLite	Yes (bun:sqlite)	node:sqlite (experimental)	via npm package
Single-file binary	bun build –compile	node:sea (experimental)	deno compile
GitHub stars (Q1 2026)	105,000	106,000	97,000

Step 1: Prerequisites and Installing Bun 1.3

Before writing a single line of code, lock down a clean environment. Mismatched runtime versions are the single most common reason Bun examples copied from blogs fail in 2026.

• Operating system: macOS 13+, Linux with glibc 2.31+ (Ubuntu 22.04, Debian 12, Fedora 39, Arch), or Windows 10 22H2 / Windows 11 with PowerShell 5.1+. ARM64 and x64 are first-class.
• Bun: 1.3.x stable. Confirm with bun --version.
• Editor: Visual Studio Code 1.95+ with the official oven.bun-vscode extension, or any editor with Language Server Protocol support.
• Optional Node fallback: Node.js 22.11.0 LTS, only required if you want to A/B test against the Node runtime.
• Optional container runtime: Docker 26.1+ or Podman 5.x for the deployment step.
• Disk space: Bun installs into roughly 90 MB; allow 1 GB for project dependencies and build artefacts.

Install on macOS or Linux with the official one-liner from the Bun installation docs.

# macOS and Linux
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

# Verify
bun --version
# Expected: 1.3.x

bun --revision
# Expected: 1.3.x+<short-git-hash>

Pitfall #1: PATH not refreshed. The installer appends ~/.bun/bin to your shell rc file but does not source it for the current session. If bun: command not found appears, run source ~/.bashrc (or ~/.zshrc) or open a new terminal. On Windows, log out and back in to pick up the user PATH change.

Pitfall #2: Old global Node shim wins. If you have an nvm or volta shim earlier in PATH, bun will still resolve correctly but node will not point at Bun’s compatibility shim. That breaks tools that probe for node first. Add alias node="bun --bun" only if you are sure no transitive dependency needs the real Node binary; otherwise leave both side by side.

Step 2: Initialise the Project and Understand bun init

Create a working directory and let bun init scaffold a TypeScript project. Unlike npm init, the Bun scaffolder writes a tsconfig.json tuned for Bun’s bundler, a .gitignore, and a README.md in one shot.

mkdir bun-tutorial-api && cd bun-tutorial-api
bun init -y

# Inspect what was created
ls -la
# Expected output:
# .gitignore
# README.md
# bun.lock
# index.ts
# node_modules/
# package.json
# tsconfig.json

Open package.json and notice three things that diverge from a typical Node project: the "type": "module" field is set so every .ts file uses ES module syntax by default; the "devDependencies" entry pins @types/bun so editors get full IntelliSense for the Bun global; and the "scripts" block is empty, because Bun does not need helper scripts to run a TypeScript file directly.

Replace the generated index.ts with a Hello World that proves Bun is reading TypeScript without a transpile step.

// index.ts
const greet = (name: string): string => `Hello, ${name}, from Bun ${Bun.version}!`;
console.log(greet("Tech Insider"));

// Run it
// $ bun run index.ts
// Expected: Hello, Tech Insider, from Bun 1.3.x!

Pitfall #3: bun init -y inside an existing Node project. The flag overwrites tsconfig.json without prompting if one already exists. Always run bun init in an empty directory or pass --no-tsconfig if you want to keep your existing TS config.

Step 3: Mastering bun install for Package Management

Bun’s package manager replaces npm, yarn, and pnpm in one binary. It writes a bun.lock file (the legacy binary bun.lockb from 1.0 was replaced by a text format in 1.2 to play nicely with code review). The resolver runs in parallel against the global module cache stored under ~/.bun/install/cache and uses hard links on Linux and macOS, so installing the same dependency twice across projects costs almost zero disk.

# Add runtime dependencies for the API we will build
bun add hono zod jose

# Add dev dependencies (Bun infers the --dev flag from the <dep>@dev shorthand too)
bun add -d @types/node typescript

# Inspect resolved tree
bun pm ls
# Expected output (truncated):
# [email protected] /Users/you/bun-tutorial-api
# ├── [email protected]
# ├── [email protected]
# └── [email protected]

Behind the scenes, Bun has hashed the resolved tree into bun.lock and pinned exact versions. To enforce reproducibility in CI, run bun install --frozen-lockfile. To prune dependencies that drifted out of package.json, run bun install --production. To audit for known vulnerabilities, the new bun audit subcommand was promoted to stable in 1.3 and queries the same advisory database that npm uses.

Pitfall #4: Native modules and postinstall scripts. Bun runs postinstall scripts only for packages on its trusted-dependencies list. If a native module like better-sqlite3 or sharp fails with “binding not found,” add the package name under "trustedDependencies" in package.json and re-run bun install. The Bun team makes this opt-in to neutralise the supply-chain attacks that hit the npm ecosystem in 2025-2026, including the high-profile incident we covered in our npm supply chain attack write-up.

Step 4: Building Your First HTTP Server with Bun.serve()

Bun ships its own HTTP server, exposed as Bun.serve(). The API mirrors the WHATWG Request and Response objects you already know from the browser fetch API, which makes the same handler portable to Cloudflare Workers, Deno Deploy, and Vercel Edge Functions.

// src/server.ts
const server = Bun.serve({
 port: 3000,
 hostname: "0.0.0.0",
 development: process.env.NODE_ENV !== "production",

 fetch(req) {
 const url = new URL(req.url);

 if (url.pathname === "/") {
 return new Response("Bun is alive on " + Bun.version);
 }

 if (url.pathname === "/health") {
 return Response.json({ status: "ok", uptime: process.uptime() });
 }

 return new Response("Not found", { status: 404 });
 },

 error(err) {
 console.error(err);
 return new Response("Internal Server Error", { status: 500 });
 },
});

console.log(`Listening on http://${server.hostname}:${server.port}`);

# Run with hot reload
bun --hot run src/server.ts

# In another terminal
curl http://localhost:3000/health
# Expected: {"status":"ok","uptime":3.4172}

The --hot flag is the Bun equivalent of nodemon, but it preserves module state across reloads, so an in-memory cache or an open database connection survives an edit. For a clean restart use --watch instead. HTTP/3 QUIC support landed in 1.2: pass a tls option with cert and key buffers and Bun will negotiate ALPN automatically.

Pitfall #5: process.env vs Bun.env. Both work, but Bun.env reads from a typed cache populated at startup, so changing .env at runtime is invisible to Bun.env until the process restarts. Stick with process.env in code that needs to react to live config changes.

Step 5: Adding the Hono Router for a Real REST API

Hand-rolled URL parsing scales badly. Hono is the de-facto Bun-friendly router, written in TypeScript, with first-class middleware, a 14 KB minified footprint, and the same Web Standards Request/Response contract as Bun.serve(). We will build the rest of the API on Hono so the code is portable to any edge runtime later.

// src/app.ts
import { Hono } from "hono";
import { logger } from "hono/logger";
import { cors } from "hono/cors";

export const app = new Hono();

app.use("*", logger());
app.use("/api/*", cors({ origin: ["http://localhost:5173"] }));

app.get("/", (c) => c.text(`Bun ${Bun.version} + Hono ready`));

app.get("/api/health", (c) =>
 c.json({ status: "ok", uptime: process.uptime(), pid: process.pid }),
);

export default {
 port: 3000,
 fetch: app.fetch,
};

Notice the export shape. When the default export of an entry file is an object with a fetch property, Bun automatically wires it into Bun.serve(), so the file is its own server. Run it with bun --hot run src/app.ts and you get logging, CORS, and JSON responses without writing a single line of plumbing.

Step 6: Persisting Data with bun:sqlite

Every Bun installation embeds SQLite via the bun:sqlite module. There is nothing to install, no native build step, and no better-sqlite3 dependency. Benchmarks published in the Bun 1.3 release notes show bun:sqlite running INSERT statements roughly 4x faster than the popular better-sqlite3 npm package on a 1 million row workload, courtesy of a hand-tuned C binding plus prepared statement caching.

If you have used SQLite with Python before, the API will look familiar. Our recent SQLite Python tutorial covers the SQL fundamentals; here we focus on Bun’s bindings.

// src/db.ts
import { Database } from "bun:sqlite";

const dbPath = process.env.DB_PATH ?? "data.db";
export const db = new Database(dbPath, { create: true, strict: true });

// WAL mode is non-default but recommended for concurrent reads.
db.exec("PRAGMA journal_mode = WAL;");
db.exec("PRAGMA foreign_keys = ON;");

db.exec(`
 CREATE TABLE IF NOT EXISTS users (
 id INTEGER PRIMARY KEY AUTOINCREMENT,
 email TEXT NOT NULL UNIQUE,
 password TEXT NOT NULL,
 created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
 );
 CREATE TABLE IF NOT EXISTS articles (
 id INTEGER PRIMARY KEY AUTOINCREMENT,
 user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
 title TEXT NOT NULL,
 body TEXT NOT NULL,
 published INTEGER NOT NULL DEFAULT 0,
 created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
 );
`);

The strict: true option, new in Bun 1.3, throws on parameter type mismatches instead of silently coercing, which catches a class of bugs early. WAL mode is recommended for any HTTP workload because writers no longer block readers.

Pitfall #6: Single connection across a fork. SQLite does not tolerate sharing a connection across forked processes. Bun’s Bun.serve() runs in a single process by default, so this is fine, but if you opt into the new reusePort: true cluster mode, open one Database per worker.

Step 7: Validating Requests with Zod and Hono Middleware

Reject malformed input at the door. Zod 3.x integrates with Hono through the official @hono/zod-validator middleware. The schema doubles as TypeScript types via z.infer, so the rest of the codebase stays type-safe without duplicate definitions.

bun add @hono/zod-validator

// src/schemas.ts
import { z } from "zod";

export const credentialsSchema = z.object({
 email: z.string().email().max(254),
 password: z.string().min(12).max(128),
});

export const articleSchema = z.object({
 title: z.string().min(1).max(160),
 body: z.string().min(1).max(20_000),
 published: z.boolean().optional().default(false),
});

export type Credentials = z.infer<typeof credentialsSchema>;
export type ArticleInput = z.infer<typeof articleSchema>;

// src/routes/articles.ts
import { Hono } from "hono";
import { zValidator } from "@hono/zod-validator";
import { db } from "../db";
import { articleSchema } from "../schemas";

export const articles = new Hono();

articles.get("/", (c) => {
 const rows = db.query(
 "SELECT id, title, published, created_at FROM articles ORDER BY id DESC LIMIT 50",
 ).all();
 return c.json(rows);
});

articles.post("/", zValidator("json", articleSchema), (c) => {
 const userId = c.get("userId") as number;
 const data = c.req.valid("json");
 const row = db.query(
 `INSERT INTO articles (user_id, title, body, published)
 VALUES ($u, $t, $b, $p) RETURNING id`,
 ).get({ u: userId, t: data.title, b: data.body, p: data.published ? 1 : 0 });
 return c.json(row, 201);
});

Step 8: Hashing Passwords with Bun.password

Bun ships a hardware-accelerated Bun.password module that wraps Argon2id and bcrypt. Argon2id is the OWASP-recommended algorithm for new applications in 2026 and what we will use here. The implementation runs the heavy compression in native code via libargon2, so a typical hash on a modern laptop completes in around 60 milliseconds at the recommended OWASP profile.

// src/password.ts
export async function hashPassword(plain: string): Promise<string> {
 return Bun.password.hash(plain, {
 algorithm: "argon2id",
 memoryCost: 19_456, // 19 MiB, OWASP 2024 profile
 timeCost: 2,
 });
}

export function verifyPassword(plain: string, hash: string): Promise<boolean> {
 return Bun.password.verify(plain, hash);
}

The verify helper is constant-time and parses the algorithm from the hash prefix, so rotating from bcrypt to argon2id later does not require a schema change.

Step 9: Issuing JWTs with jose for Stateless Auth

For the auth layer we will issue HS256 JSON Web Tokens via the jose package. Bun supports the WebCrypto SubtleCrypto API natively, which is what jose uses under the hood, so there is no native binding to compile.

// src/auth.ts
import { SignJWT, jwtVerify } from "jose";
import { Hono } from "hono";
import { zValidator } from "@hono/zod-validator";
import { credentialsSchema } from "./schemas";
import { hashPassword, verifyPassword } from "./password";
import { db } from "./db";

const secret = new TextEncoder().encode(
 process.env.JWT_SECRET ?? "dev-secret-change-me-please-32-bytes-min",
);

export async function issueToken(userId: number): Promise<string> {
 return new SignJWT({ sub: String(userId) })
 .setProtectedHeader({ alg: "HS256" })
 .setIssuedAt()
 .setExpirationTime("1h")
 .sign(secret);
}

export const auth = new Hono();

auth.post("/register", zValidator("json", credentialsSchema), async (c) => {
 const { email, password } = c.req.valid("json");
 const hash = await hashPassword(password);
 try {
 const row = db.query(
 "INSERT INTO users (email, password) VALUES ($e, $p) RETURNING id",
 ).get({ e: email, p: hash }) as { id: number };
 return c.json({ token: await issueToken(row.id) }, 201);
 } catch {
 return c.json({ error: "email already registered" }, 409);
 }
});

auth.post("/login", zValidator("json", credentialsSchema), async (c) => {
 const { email, password } = c.req.valid("json");
 const row = db.query(
 "SELECT id, password FROM users WHERE email = $e",
 ).get({ e: email }) as { id: number; password: string } | undefined;

 if (!row || !(await verifyPassword(password, row.password))) {
 return c.json({ error: "invalid credentials" }, 401);
 }
 return c.json({ token: await issueToken(row.id) });
});

export async function requireAuth(c: any, next: any) {
 const header = c.req.header("authorization") ?? "";
 const token = header.startsWith("Bearer ") ? header.slice(7) : "";
 try {
 const { payload } = await jwtVerify(token, secret);
 c.set("userId", Number(payload.sub));
 await next();
 } catch {
 return c.json({ error: "unauthorized" }, 401);
 }
}

Wire the auth router and the protected articles router into src/app.ts:

// src/app.ts (final)
import { Hono } from "hono";
import { logger } from "hono/logger";
import { cors } from "hono/cors";
import { auth, requireAuth } from "./auth";
import { articles } from "./routes/articles";

export const app = new Hono();
app.use("*", logger());
app.use("/api/*", cors());

app.route("/auth", auth);
app.use("/api/articles/*", requireAuth);
app.route("/api/articles", articles);

app.notFound((c) => c.json({ error: "not found" }, 404));
app.onError((err, c) => {
 console.error(err);
 return c.json({ error: "internal" }, 500);
});

export default { port: 3000, fetch: app.fetch };

Smoke-test the full flow with curl:

# Register
curl -s -X POST http://localhost:3000/auth/register \
 -H 'content-type: application/json' \
 -d '{"email":"[email protected]","password":"correcthorsebatterystaple"}'
# Expected: {"token":"eyJhbGciOiJIUzI1NiIs..."}

TOKEN="eyJ..." # paste from above

curl -s -X POST http://localhost:3000/api/articles \
 -H "authorization: Bearer $TOKEN" \
 -H 'content-type: application/json' \
 -d '{"title":"Hello Bun","body":"My first article","published":true}'
# Expected: {"id":1}

Step 10: Writing Tests with bun test

Bun’s built-in test runner reads describe, it, expect, beforeAll, afterEach, and the rest of the Jest globals from a single bun:test import. There is no Jest, Vitest, or ts-node setup, no separate config file, and no transform pipeline. The runner discovers any file matching *.test.ts, *.spec.ts, or files inside a __tests__ folder. Running the suite finishes in milliseconds, even for a few hundred specs.

// src/auth.test.ts
import { describe, expect, it, beforeAll } from "bun:test";
import { hashPassword, verifyPassword } from "./password";
import { app } from "./app";

describe("password helpers", () => {
 it("verifies a correct password", async () => {
 const hash = await hashPassword("correcthorsebatterystaple");
 expect(await verifyPassword("correcthorsebatterystaple", hash)).toBe(true);
 });
 it("rejects an incorrect password", async () => {
 const hash = await hashPassword("correcthorsebatterystaple");
 expect(await verifyPassword("wrong", hash)).toBe(false);
 });
});

describe("HTTP layer", () => {
 let token: string;
 const email = `t-${Date.now()}@example.com`;

 beforeAll(async () => {
 const res = await app.request("/auth/register", {
 method: "POST",
 headers: { "content-type": "application/json" },
 body: JSON.stringify({ email, password: "correcthorsebatterystaple" }),
 });
 expect(res.status).toBe(201);
 token = (await res.json()).token;
 });

 it("rejects unauthenticated POST /api/articles", async () => {
 const res = await app.request("/api/articles", { method: "POST" });
 expect(res.status).toBe(401);
 });

 it("creates an article when authenticated", async () => {
 const res = await app.request("/api/articles", {
 method: "POST",
 headers: {
 "content-type": "application/json",
 authorization: `Bearer ${token}`,
 },
 body: JSON.stringify({ title: "T", body: "B", published: true }),
 });
 expect(res.status).toBe(201);
 });
});

# Run the suite
bun test

# Expected output (truncated)
# bun test v1.3.x
# src/auth.test.ts:
# (pass) password helpers > verifies a correct password [62.40ms]
# (pass) password helpers > rejects an incorrect password [121.14ms]
# (pass) HTTP layer > rejects unauthenticated POST /api/articles [3.10ms]
# (pass) HTTP layer > creates an article when authenticated [9.27ms]
#
# 4 pass, 0 fail, 11 expect() calls
# Ran 4 tests across 1 files. [0.42s]

For coverage, pass --coverage. The runner uses V8-style line and function counters, prints to stdout, and writes an lcov.info file when invoked with --coverage-reporter=lcov, which slots straight into Codecov or Coveralls.

Pitfall #7: Shared SQLite database across tests. The example above writes to the same data.db used by the dev server. In CI, point DB_PATH at :memory: by setting process.env.DB_PATH = ":memory:" in a preload script or a beforeAll hook to keep tests isolated.

Step 11: Bundling and Compiling to a Single Binary

Bun’s bundler ships in the same binary as the runtime, exposed as bun build. It produces ES module output by default, supports tree-shaking, and can target the browser, Node, or Bun. The killer feature is --compile, which embeds the runtime alongside your bundle into a single self-contained executable that runs without Bun installed on the target machine.

# Bundle to a single JS file
bun build src/app.ts \
 --outfile dist/app.js \
 --target bun \
 --minify

# Or compile to a standalone binary
bun build src/app.ts \
 --compile \
 --minify \
 --sourcemap \
 --outfile dist/api

# Run it directly
./dist/api
# Expected: server starts on :3000 with no Bun in PATH

The compiled binary is around 60 MB on Linux x64 because it embeds the JavaScriptCore engine plus your code. Cross-compile by passing --target=bun-linux-x64, --target=bun-darwin-arm64, and similar values. As of Bun 1.3 the supported matrix covers Linux x64, Linux arm64, macOS x64, macOS arm64, and Windows x64.

Pitfall #8: Dynamic imports in compiled binaries. Bun’s compiler statically traces imports. A dynamic-string await import(name) where name is computed at runtime will fail to resolve at boot. Move dynamic plugins behind a static import map or pass --external pkg-name at build time and ship the dependency next to the binary.

Step 12: Containerising with Docker and Multi-Stage Builds

Bun publishes official images on Docker Hub at oven/bun. The distroless variant is around 90 MB compressed and ships only the Bun binary plus glibc, which gives you the smallest practical attack surface for production. Use a multi-stage build to install dependencies once, then copy the built artefact into the slim runtime image.

# Dockerfile
FROM oven/bun:1.3 AS builder
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile --production
COPY . .
RUN bun build src/app.ts --target bun --outfile dist/app.js --minify

FROM oven/bun:1.3-distroless AS runtime
WORKDIR /app
COPY --from=builder /app/dist/app.js ./app.js
COPY --from=builder /app/node_modules ./node_modules
ENV NODE_ENV=production
EXPOSE 3000
CMD ["bun", "run", "app.js"]

docker build -t bun-tutorial-api .
docker run --rm -p 3000:3000 -e JWT_SECRET=$(openssl rand -hex 32) bun-tutorial-api

# Image size
docker images bun-tutorial-api
# Expected: ~150-180 MB depending on dependency tree

For Kubernetes, the same image runs unmodified. Bun’s process model is single-process by default, so set CPU requests to one full core per pod and rely on horizontal scaling rather than worker threads, at least until 1.4 ships full worker parity.

Step 13: Going to Production: CI, Monitoring, and Performance

The final step locks in the production gates. We want a CI workflow that installs frozen dependencies, runs bun test, builds the artefact, and pushes the Docker image. The community has converged on the official oven-sh/setup-bun@v2 GitHub Action.

# .github/workflows/ci.yml
name: ci
on: [push, pull_request]
jobs:
 test:
 runs-on: ubuntu-24.04
 steps:
 - uses: actions/checkout@v4
 - uses: oven-sh/setup-bun@v2
 with:
 bun-version: 1.3.x
 - run: bun install --frozen-lockfile
 - run: bun test --coverage
 - run: bun build src/app.ts --target bun --outfile dist/app.js --minify

For load testing, run a TechEmpower-style smoke test with oha or wrk:

oha -z 30s -c 256 http://localhost:3000/
# Expected on a 4-core 2024 laptop:
# Requests/sec: ~250,000+
# Latency p99 : ~3 ms

For observability, expose Prometheus metrics through hono/prometheus middleware and surface them on a /metrics endpoint, then scrape from Grafana. We covered the metrics-vs-dashboard split in our Prometheus vs Grafana comparison; the same conclusions apply when the runtime is Bun rather than Node.

Common Pitfalls and How to Avoid Them

• Pitfall #9: Worker threads parity. Bun 1.3 implements worker_threads for most use cases but does not yet support SharedArrayBuffer with Atomics.wait on Windows. CPU-bound parallelism on Windows still requires Node.js fallback or process-level scaling.
• Pitfall #10: Native bindings. Packages distributing prebuilt N-API binaries usually work. Anything still using the legacy nan bindings (e.g. some older imaging libs) will fail. Check the Bun GitHub repo compatibility table before adopting an unfamiliar dependency.
• Pitfall #11: ESM-only ecosystem assumptions. Bun runs both CJS and ESM, but mixing require and dynamic import in the same file can confuse the resolver. Pick one module system per file.
• Pitfall #12: Default fetch is keepalive-less in 1.3. A loop calling fetch() against the same host opens new sockets every time. Reuse an explicit Bun.fetch.preconnect() pool until the 1.4 keepalive lands.
• Pitfall #13: Test runner globals shadow your code. Importing describe and it from a file that is not under bun test evaluation will throw “globals not available.” Wrap test-only imports inside __tests__ folders or rely on the bun:test module path.

Troubleshooting Bun JavaScript: Eight Common Errors

The error messages below are the eight most reported failures on the Bun GitHub issue tracker between October 2025 and March 2026. Each one comes with a one-line fix that has shipped to stable.

Symptom	Likely Cause	Fix
error: Cannot find package "X"	npm package missing peer dep that Bun does not auto-install	Add the peer manually with bun add X
postinstall script blocked	Untrusted dependency tried to run postinstall	Add to trustedDependencies in package.json
EACCES on bun install	~/.bun owned by root after sudo install	sudo chown -R $USER ~/.bun
SQLite: database is locked	Multiple writers on a non-WAL DB	db.exec("PRAGMA journal_mode = WAL;")
Bun.serve EADDRINUSE	Hot reload left a stale socket	Pass reusePort: true or kill leftover PID
jose: invalid key length	JWT secret shorter than 32 bytes for HS256	Use openssl rand -hex 32
fetch failed: ENOTFOUND	DNS over HTTPS misconfigured in 1.3.0	Upgrade to 1.3.1+ or set BUN_CONFIG_DNS_OVER_HTTPS=0
compiled binary segfaults on Alpine	musl libc not yet supported by –compile	Use oven/bun:1.3-debian base image

Advanced Tips: Pushing Bun JavaScript Further

• Use Bun.SQL for Postgres. Bun 1.3 ships a built-in Postgres driver that returns rows as plain objects and reuses connections via a built-in pool. It performed roughly 50% faster than pg in independent benchmarks published at the 1.3 launch.
• Inline workers with new Worker(new URL(…)). Bun resolves worker entry files at bundle time, so a worker pool ships in the same compiled binary as the main process.
• Replace dotenv. Bun automatically reads .env, .env.local, and .env.<NODE_ENV> in that order. The dotenv npm package is unnecessary and slightly slower because it adds a synchronous file read on import.
• Run Bun on AWS Lambda. Use the official Bun custom runtime layer published in late 2025; cold starts measured around 35 milliseconds, half the cold start of the Node 22 managed runtime.
• Stream large responses with ReadableStream. The Bun.serve() handler accepts a streaming body, so an LLM token stream or a large file download does not buffer in memory.
• Profile with –inspect. Bun speaks the WebKit Inspector protocol, so attach Safari Web Inspector or the Bun VS Code extension for flame graphs without instrumenting your code.
• Type-check on CI without ts-node. bun x tsc --noEmit uses Bun to run the TypeScript compiler binary. The compile step is purely for type-checking; the runtime never needs the emitted JS.
• Combine with Vite for the frontend. Bun runs Vite faster than Node thanks to its own bundling primitives. Our Vite vs Webpack comparison covers the trade-offs in detail.

Bun JavaScript vs Node.js in 2026: The Honest Verdict

Bun is ready for greenfield production work. The 1.3 release closed most of the historic gaps with Node.js, the package manager is materially faster, and the developer experience benefits from baked-in TypeScript and a Jest-compatible test runner. For new APIs, edge functions, CLIs, and bundled SaaS tooling, Bun is the safer pick on raw performance and tooling cohesion.

Node.js still wins for two scenarios. The first is enterprise applications that depend on the long tail of native bindings or on debug tooling such as legacy APM agents that require N-API hooks Bun has not yet implemented. The second is teams running on Alpine Linux or other musl libc distributions, where the --compile output is not supported and the official images add unnecessary glibc weight. In those cases, Node 22 LTS remains the conservative default.

Where does Deno fit? Deno’s permission model and standard library are still excellent for security-conscious workloads, but Deno’s adoption has flattened, and its 2.x release in late 2024 conceded the package-management war by adopting npm compatibility. If you want a single tool that does everything, Bun is the more complete answer in 2026.

FAQ: Bun JavaScript Tutorial

Is Bun JavaScript production-ready in 2026?

Yes for most workloads. Bun 1.3 has been on a stable release line since March 2025 with monthly patch releases. Companies including Vercel, Render, and Fly.io ship Bun-based runtimes. The two caveats are native bindings that still require Node and Alpine-based deployments where --compile is not supported.

Can I use existing npm packages with Bun?

Around 95% of the npm registry runs unmodified under Bun, including Express, Fastify, Hono, Prisma, Drizzle, Zod, and the entire React/Next.js ecosystem. The compatibility list at the Bun documentation tracks the remaining 5% with workarounds.

How fast is Bun compared to Node.js?

In published TechEmpower Round 25 results from Q1 2026, Bun.serve() handles around 1 million plaintext requests per core per second, versus around 400,000 for Express on Node 22. Cold starts fell from 45 milliseconds on Node to roughly 1.2 milliseconds on Bun, a 37x improvement. Real-world deltas depend on workload mix.

Does Bun replace npm and yarn?

For new projects, yes. bun install reads the same package.json and writes a bun.lock file. The CLI is roughly 5x faster than npm install on a typical Next.js project. You can keep npm installed in parallel with no conflicts.

Can Bun build a single executable like Deno or Go?

Yes. bun build --compile produces a self-contained binary around 60 MB that embeds the JavaScriptCore runtime. It supports cross-compilation to Linux x64, Linux arm64, macOS x64, macOS arm64, and Windows x64 as of Bun 1.3.

Does Bun support TypeScript natively?

Yes. Run bun run script.ts directly with no transpile step. Bun 1.3 added native decorator transforms, so frameworks like NestJS run unmodified. Type-checking still happens with tsc via bun x tsc --noEmit because Bun does not perform type-checking at runtime.

Is Bun a good choice for a monorepo?

Yes. Bun supports workspaces in package.json with "workspaces": ["packages/*"], and bun install resolves cross-package symlinks. Combined with bun --filter for running scripts in a subset of packages, it covers most pnpm and Turborepo workflows without extra tooling.

Where can I learn more about Bun?

Start with the official Bun documentation, the Bun GitHub repository for source and issues, and the Node.js documentation when you need to verify Bun’s compatibility surface against the upstream API.

Related Coverage

• TypeScript vs JavaScript 2026: 73% Adoption, 15% Salary Gap [Tested]
• Vite vs Webpack 2026: 24x HMR Speed and 115M Downloads
• Yarn vs npm 2026: 3.7x Faster Installs and 85% Disk Savings [Tested]
• How to Build a Full-Stack App with Next.js: 13-Step Tutorial
• FastAPI Tutorial: Build a REST API in 13 Steps [2026]
• How to Master SQLite with Python: 13-Step Tutorial
• Best AI Coding Tools 2026 Guide

Last updated April 04, 2026. All benchmarks reflect Bun 1.3.x stable on Linux x64 unless otherwise noted. Performance figures cited from official Bun release notes, the TechEmpower Round 25 benchmark suite, and MuchSkills’ 2026 developer survey.