How to Use Bun: The Beginner's Guide (First Install, First Script, Built-in Server, and the Test Runner)

CodexFuse Team · 2026-10-31T03:57:27.257Z · 12 min read

Install Bun free, scaffold your first project, run TypeScript with no build step, build a Bun.serve server, and test it — the beginner's guide to the fast JS runtime.

Learning how to use Bun starts with one idea: it is a JavaScript toolkit that replaces four separate tools with a single command. Bun works as a runtime that executes your code, a package manager that installs dependencies, a bundler that prepares production builds, and a test runner that checks your work. This guide walks you through the full beginner path, from installing Bun to running TypeScript, building a web server, and testing your first project. Once your first server is running, you can send it real HTTP requests with our free API tester to see the responses come back.

What Is Bun, in Plain Terms?

Bun is an all-in-one toolkit for JavaScript and TypeScript. One executable, named bun, runs your code, installs your packages, bundles your app for production, and runs your tests. It is built on JavaScriptCore, the same JavaScript engine Apple ships in Safari, with performance-critical parts written in the Zig systems language.

For a beginner, the practical difference from the classic Node.js setup is setup friction. A typical Node project needs Node itself, a package manager like npm or pnpm, a build tool for TypeScript, and a separate test framework. With Bun, the same project needs exactly one install. TypeScript files run directly with no compiler config, packages install with one command, and tests run with another.

Bun aims to be compatible with the Node.js ecosystem. It supports many familiar Node modules and globals, including process, Buffer, and modules such as node:fs and node:path, and most npm packages install and run under Bun. Compatibility is not absolute, so you should test your specific project before moving anything important to it.

How Do You Use Bun? The 4-Step Path

Here is the shortest complete path from zero to a working Bun project. Each step is one command.

1. Install Bun with the official script for your operating system (one line on macOS and Linux, one line in PowerShell on Windows).
2. Create a project with bun init, which scaffolds a basic project and asks which template you want.
3. Run your code with bun run index.ts — TypeScript included, no build step.
4. Test your code with bun test — the test runner is built in, no framework to install.

The rest of this guide expands each step, then adds packages, a web server, bundling, and the honest comparison with Node.js and Deno.

How to Install Bun on macOS, Linux, and Windows

Installing Bun takes one command on every major desktop platform. Bun ships as a single, dependency-free executable, so there is no installer wizard and no long dependency chain. Pick your platform:

Two platform notes from Bun's own installation documentation. On Linux, you need the unzip package first (sudo apt install unzip on Debian/Ubuntu), and Bun recommends kernel 5.6 or newer. Native Windows support arrived with Bun 1.1, released April 1, 2024 — before that, Windows users needed WSL.

After installing, verify it works:

bun --version

If the terminal says "command not found", the install directory (~/.bun/bin) is not on your PATH. The install script usually adds it to your shell profile automatically; if not, add it manually and restart the terminal.

Upgrading later is one command: bun upgrade (use your package manager's upgrade command instead if you installed through Homebrew or npm).

Your First Bun Project: bun init and Your First Script

Start a project with bun init. The command asks which template you want: Blank, React, or Library. Choose Blank for this guide. It creates a project folder with an index.ts file, a package.json, and a TypeScript config.

Open the project folder and replace index.ts with:

console.log("Hello from Bun!");

Run it:

bun run index.ts

The terminal prints Hello from Bun!. For simple files you can skip run entirely — bun index.ts works too.

Running project scripts

Bun executes the scripts section of your package.json just like npm does. Add a script:

{
  "scripts": {
    "dev": "bun --watch run index.ts",
    "start": "bun run index.ts"
  }
}

Then run bun run dev. The --watch flag restarts your program automatically when files change, which is how most developers run a dev loop. Bun's docs report that bun run carries roughly 28 times less overhead than npm run (about 6ms versus 170ms), because it skips npm's process-spawning machinery.

How Bun Runs TypeScript With No Build Step

Bun executes TypeScript files directly. No tsc step, no config file, no waiting. Save this as user.ts:

interface User {
  name: string;
  email: string;
}

const user: User = {
  name: "Alex",
  email: "[email protected]",
};

console.log(`Welcome, ${user.name}`);

bun run user.ts

Bun strips the TypeScript syntax and runs the resulting JavaScript. This is transpilation, not type checking: Bun will happily run code with type errors. For a beginner project that is fine, but add a type check to your workflow as the project grows — either tsc --noEmit or Bun's own bun test --check flag, which type-checks your test files and everything they import before running them.

Bun also handles JSX and TSX files natively, which makes it useful for tooling around React projects. You still keep your framework's own dev server and build commands for the app itself; Bun just slots into the workflow wherever you want speed.

How to Install Packages With bun add

Bun includes its own package manager. For a project that already has a package.json, install everything with:

bun install

Add a new dependency with:

bun add hono

Add a dev dependency with the -d flag, and remove one with bun remove:

bun add -d typescript
bun remove hono

Bun writes a bun.lock lockfile at the project root. Commit it to version control so installs stay reproducible; in CI, bun ci (equivalent to bun install --frozen-lockfile) installs exactly what the lockfile records and fails if package.json disagrees.

Bun's documentation reports that bun install can be up to 25 times faster than npm, thanks to a global package cache and platform-specific install tricks (hardlinks on Linux and Windows, copy-on-write clones on macOS). Treat that as the project's own benchmark claim, not a guarantee for your machine — your mileage depends on network, disk, and cache state. One security behavior worth knowing: unlike npm, Bun does not run arbitrary postinstall lifecycle scripts of installed dependencies unless they are trusted.

Bun add vs pnpm: an honest line

If you already use pnpm, you do not have to switch everything to Bun. Many teams keep pnpm as their package manager and use Bun only as a runtime (bun run dev), or the reverse: install with bun install but keep running the app on Node. The two are not interchangeable — pnpm is a package manager only, while Bun is a runtime plus package manager plus bundler plus test runner. Pick one authoritative package manager per project and commit its lockfile; mixing lockfiles is how you get unreproducible installs.

How to Build a Web Server With Bun.serve

Bun has an HTTP server built into the runtime — no Express install needed for a simple service. Save this as server.ts:

const server = Bun.serve({
  port: 3000,
  fetch(request) {
    return new Response("Hello from Bun!");
  },
});

console.log(`Server running at http://localhost:${server.port}`);

bun run server.ts

Visit http://localhost:3000 in your browser and you will see the response. The fetch handler receives every request and returns a standard Web Response, so the same code style you know from service workers and edge functions works here.

For a real API you will want routing. Add a framework like Hono (bun add hono) instead of hand-rolling routes — Bun.serve handles the socket layer, the framework handles the URL layer. Bun also includes WebSocket server support, so chat apps and live dashboards do not need an extra dependency for the socket part.

How to Run Tests With the Built-in Test Runner

Bun ships a Jest-compatible test runner, so there is nothing to install. Save a function in math.js:

export function add(a, b) {
  return a + b;
}

Write the test in math.test.js:

import { test, expect } from "bun:test";
import { add } from "./math.js";

test("adds two numbers", () => {
  expect(add(2, 3)).toBe(5);
});

bun test

Bun finds test files automatically — any file matching *.test.*, *_test.*, *.spec.*, or *_spec.* across JS, TS, JSX, and TSX extensions. The API will feel familiar if you have used Jest: describe, it, expect, lifecycle hooks (beforeAll, beforeEach, afterEach, afterAll), mocks, and snapshot testing are all supported.

Useful flags as your suite grows:

• bun test --watch — re-run tests when files change.
• bun test --coverage — generate a coverage report.
• bun test --parallel — spread test files across CPU cores.
• bun test -t "adds" — run only tests whose name matches.
• bun test --bail — stop after the first failure (handy in CI).

In CI, the official oven-sh/setup-bun GitHub Action installs Bun, and bun test automatically emits GitHub Actions annotations — no config needed. GitLab users can add --reporter=junit --reporter-outfile report.xml for test reports the pipeline understands.

How to Bundle Your App With bun build

When it is time to ship, Bun's bundler prepares your code for its target environment:

bun build ./src/index.ts --outdir ./dist

Targeting a browser? Add the target flag:

bun build ./src/index.ts --target browser --outdir ./dist

The bundler handles TypeScript, JSX, minification, tree shaking, and code splitting. The rule of thumb: small scripts and servers run directly with bun run and never need a bundle; browser apps do, because browsers cannot run raw TypeScript or your module layout. Complex apps may still prefer their framework's own build pipeline (Vite, Next.js, Astro) — Bun complements those tools rather than replacing them.

Bun vs Node.js: Should You Switch?

Bun and Node.js both run JavaScript outside the browser, but they come from different philosophies. Node is the mature incumbent; Bun is the integrated challenger. Here is the honest comparison:

The switching rule is simple: start new experiments and side projects on Bun, keep production systems with specialized native modules on Node until you have tested them under Bun. Many developers land in the middle — installing with bun install for speed while the app still runs on Node.

Bun vs Deno: Two Modern Runtimes

Deno is the other modern JavaScript/TypeScript runtime with integrated tooling, and beginners often compare it with Bun. The two differ in design priorities: Bun optimizes for speed and Node.js compatibility, so existing npm projects usually migrate with little friction; Deno optimizes for explicit permissions and web standards, so code written for Deno tends to be more locked-down by default. There is no universal winner — compare them against your project's actual needs (which packages you depend on, where you deploy, what your team already knows) rather than headline benchmark claims.

The Complete Bun Command Cheat Sheet

Every command a beginner needs, in one table. Bookmark this section.

What to Do After Your First Bun Project

Your first project is a starting point, not a destination. Put it under version control with our GitHub beginner guide so you never lose working code. When your Bun.serve app needs a database, our Supabase beginner guide pairs a Postgres backend with your API in an afternoon. Ready to ship? Our Docker beginner guide shows how to containerize a Node-style app — the same pattern works for Bun — and our GitLab beginner guide covers the CI pipeline where bun ci and the JUnit reporter earn their keep.

Sources

• Bun Documentation — Installation (bun.sh/docs/installation): install methods per platform, the Linux unzip requirement, PATH troubleshooting, bun upgrade. Fetched 2026-10-30.
• Bun Documentation — Quickstart (bun.sh/docs/quickstart): bun init templates (Blank, React, Library), running index.ts, the Bun.serve example on localhost:3000, and the claim that bun run is roughly 28x faster than npm run (6ms vs 170ms overhead). Fetched 2026-10-30.
• Bun Documentation — Test runner (bun.sh/docs/cli/test): Jest-compatible API, test file patterns, --watch, --coverage, --parallel, --check type checking, GitHub Actions annotations with the oven-sh/setup-bun action, and JUnit reporting. Fetched 2026-10-30.
• Bun Documentation — bun install (bun.com/docs/pm/cli/install): the claim of up to 25x faster installs than npm, bun.lock lockfile, bun ci as the lockfile-strict install, and no arbitrary postinstall execution for dependencies. Fetched 2026-10-30.
• SIIT — "What Is Bun? JavaScript Runtime, Package Manager, and Bundler" (siit.co, updated about 4 days before fetch): all-in-one toolkit explainer, JavaScriptCore engine and Zig implementation, transpilation vs type checking, bun.lock, Bun.serve and bun build examples, workspaces, and the Node compatibility caveat. Fetched 2026-10-30.
• dev.to — "Bun Runtime Setup Guide: Migrating from Node.js and Practical Patterns": performance claims (about 2–3x faster than Node.js, startup about one-third, native HTTP throughput about 4x Express, bun install about 25x npm), migration steps, and the Bun.serve pattern. Fetched via search 2026-10-30.
• roboin.io — "How to install Bun on Windows": native Windows support since Bun 1.1 (released April 1, 2024), the PowerShell install command, npm install -g bun, and scoop install bun. Fetched via search 2026-10-30.

Frequently Asked Questions

Is Bun a replacement for Node.js?

It can be, for many projects — but treat it as an alternative, not a drop-in guarantee. Most npm packages run under Bun, and many developers migrate existing projects successfully. Production systems with native modules or unusual Node internals should stay on Node until tested under Bun.

Can I use Bun on Windows?

Yes. Bun has shipped native Windows support since version 1.1 (April 2024). Install it from PowerShell with powershell -c "irm bun.sh/install.ps1 | iex", or via npm or Scoop if you prefer a package manager route.

Does Bun work with my existing npm packages?

Usually yes. Bun reads package.json and installs from the npm registry, and its docs aim for broad Node API compatibility. The exceptions are packages with native binaries, lifecycle-script tricks, or deep Node-internal assumptions — test those before committing.

Is Bun free to use?

Yes. Bun is free and open source, and there is no paid tier for the toolkit itself. The single binary includes the runtime, package manager, bundler, and test runner at no cost.

Do I need to know TypeScript to use Bun?

No. Bun runs plain JavaScript files with the same commands. TypeScript support is a bonus — you can start with .js files and switch to .ts whenever you want, with no new tooling to configure.