Skip to main content

Hello World (first programs) · Beginner · 14 min

Hello World in Bun: run TypeScript, serve a page and compile a binary

By Padding · Updated 18 Nov 2026
oven/bun:1.4.4 image (Debian) · Bun 1.4.4

You will install Bun 1.4, run a TypeScript Hello World with no build step, time bun install against npm install, serve a page with Bun.serve, pass a test with bun test and compile the program into one executable file.

On this page

Bun is a JavaScript and TypeScript runtime that ships as one executable file. That one file is four tools you would otherwise install separately: it runs your code like Node.js does, installs packages like npm, bundles code like esbuild or webpack, and runs tests like Jest or Vitest. Under the hood it uses JavaScriptCore, the JavaScript engine Apple builds for Safari, where Node.js and Deno use Google's V8. Bun aims to run code written for Node.js, and it mostly does, but not every Node.js API behaves identically yet. Step 8 shows how to check before you rely on it.

In this tutorial you install Bun 1.4, write a two-file TypeScript program and run it with no compile step, compare install speed with npm, serve a web page, test a function and turn the whole thing into a single binary. Every file lives in one throwaway folder that you delete at the end.

Teams pick Bun for command-line tools and scripts that should start fast, for HTTP APIs, for build and test tooling in existing JavaScript projects (sometimes only bun install and bun test while production stays on Node.js), and for shipping a JavaScript program as one file to people who do not have a runtime installed.

Step 1 · Install Bun

On Linux, the installer needs curl and unzip. On Ubuntu or Debian, install them first. macOS already has both, so skip this command there:

Bash
sudo apt update
sudo apt install -y curl unzip

Then run Bun's official install script on Linux or macOS. The bash -s "bun-v1.4.4" part pins the release this page was written against; leave it off to get the newest one:

Bash
curl -fsSL https://bun.com/install | bash -s "bun-v1.4.4"

This tutorial follows Linux and macOS: every command after this one uses a bash-style shell (heredocs, ls -a, rm -rf, time), and none of them work in PowerShell. On Windows, open a WSL terminal (Ubuntu from the Microsoft Store works) and run the Linux commands above inside it. Bun also has a native Windows installer, install.ps1, described on its installation page, but the rest of this page does not cover that set-up.

The script downloads one file, bun, into ~/.bun/bin in your home folder, and adds that folder to your shell's start-up file (~/.bashrc or ~/.zshrc). New terminals pick it up. To use Bun in the terminal you already have open, run these two lines:

Bash
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
bun --version
command -v bun

A file you install this way gets no updates from your operating system's package manager. Run bun upgrade later to move to a newer release.

Check it worked

bun --version prints 1.4.4. command -v bun prints a path ending in .bun/bin/bun, such as /home/you/.bun/bin/bun. If you get bun: command not found, open a new terminal or run the two export lines again.

Step 2 · Create a project with bun init

Make a folder and let Bun set it up:

Bash
mkdir -p ~/hello-bun
cd ~/hello-bun
bun init -y
ls -a

bun init asks which template you want (blank, React or library). The -y flag accepts the defaults, which is the blank template. It writes these files:

  • package.json: the project's name, its dependencies and a typecheck script. Bun reads the same package.json format as npm, so other tools understand the folder too.
  • index.ts: the entry point, a one-line TypeScript file that prints a greeting.
  • tsconfig.json: TypeScript settings, used by your editor and by bun check.
  • README.md and .gitignore.

If Bun detects an AI coding tool on your computer, it may also add a rules file such as CLAUDE.md. You can delete it. At the end, bun init runs bun install, which downloads @types/bun (descriptions of Bun's APIs for your editor) into node_modules/ and writes a lockfile, bun.lock.

Check it worked

ls -a lists at least package.json, index.ts, tsconfig.json, bun.lock and node_modules. Run bun index.ts and it prints the starter greeting.

Step 3 · Write Hello World in TypeScript and run it

Replace the starter code with a program in two files. The first holds a function:

Bash
cat > greet.ts <<'TS'
export function greet(name: string): string {
  return `Hello, ${name}`;
}
TS
  • export makes the function available to other files. Without it, greet would be private to greet.ts.
  • function greet(name: string): string { declares a function that takes one argument. name: string is a TypeScript type annotation: callers must pass text. The : string after the brackets says the function returns text.
  • ` return `Hello, ${name}; ` builds the result. The backticks make a template string, and `${name} inserts the value.

The second file is the entry point. It overwrites the starter index.ts:

Bash
cat > index.ts <<'TS'
import { greet } from "./greet.ts";

const name: string = Bun.argv[2] ?? "world";

console.log(greet(name));
console.log(`Running on Bun ${Bun.version}`);
TS
bun index.ts
bun index.ts Ada
  • import { greet } from "./greet.ts"; loads the function from the other file. Bun accepts the .ts extension in the path.
  • Bun.argv is the list of words on the command line. Item 0 is the path to bun, item 1 is the script, so the first word you type after the file name is item 2.
  • ?? "world" means "if the left side is missing, use this instead". With no argument, Bun.argv[2] is undefined, so name becomes "world".
  • Bun is a global object that only exists in Bun. Bun.version is the runtime's version number.
  • console.log(...) prints a line, exactly as in a browser or Node.js.

There is no tsc step and no .js file. Bun removes the type annotations as it loads each file and runs the result. It does not check that the types are right while doing so. For that, Bun 1.4.3 added a built-in checker:

Bash
bun check

Check it worked

bun index.ts prints Hello, world and Running on Bun 1.4.4. bun index.ts Ada prints Hello, Ada on the first line. ls shows no index.js. bun check prints a short success line, something like No type errors in 2 files, and exits with status 0. Change greet(name) to greet(42), run bun check again and it reports error TS2345, while bun index.ts still runs. Change it back before you continue.

Step 4 · Time bun install against npm install

Bun's package manager installs from the same npm registry and reads the same package.json. Add a real dependency so there is something to install. You will not use Express in this tutorial; it is here because it pulls in a few dozen packages:

Bash
bun add express@5.3.0

Now delete what was installed and time each tool from an empty node_modules. This step needs Node.js and npm; skip the npm lines if you do not have them. bun pm cache rm empties Bun's download cache so Bun has to fetch every package again, as npm does on a first run.

On prepaid mobile data, keep in mind that each of these two installs downloads every package again, several megabytes in total; skip the timing if data is tight. Normally you never clear the cache: Bun keeps each package it has downloaded in ~/.bun/install/cache and reuses it in every project, so a second project with the same packages installs without touching the network.

Bash
rm -rf node_modules bun.lock
time npm install
rm -rf node_modules package-lock.json
bun pm cache rm
time bun install

Check it worked

Each time line reports a real figure, the seconds you waited. Bun's real figure is usually several times smaller than npm's, though the exact numbers depend on your network, your disk and npm's own cache. package.json lists express under dependencies, and a new bun.lock exists.

Step 5 · Serve a page with Bun.serve

Bun.serve starts an HTTP server with no framework and no extra package. Create server.ts:

Bash
cat > server.ts <<'TS'
import { greet } from "./greet.ts";

const server = Bun.serve({
  port: 3000,
  fetch(req) {
    const url = new URL(req.url);
    if (url.pathname === "/") {
      return new Response(`<h1>${greet("web")}</h1>`, {
        headers: { "Content-Type": "text/html; charset=utf-8" },
      });
    }
    return new Response("Not found", { status: 404 });
  },
});

console.log(`Listening on ${server.url}`);
TS
  • Bun.serve({ ... }) starts the server and returns an object describing it.
  • port: 3000 is the port to listen on. Pick another number if something already uses 3000.
  • fetch(req) runs once for every request and must return a Response. Request and Response are the same web-standard classes browsers use for fetch().
  • new URL(req.url) splits the address into parts, so url.pathname is the path, such as /.
  • The home page gets an HTML heading with a Content-Type header. charset=utf-8 tells the browser how to read the bytes, so names such as Ọlá or Nnamdi, or text in Amharic or Arabic, display correctly.
  • Every other path gets the text Not found with status 404.

Start it. The server keeps running in this terminal until you press Ctrl+C:

Bash
bun server.ts

In a second terminal, request both paths:

Bash
curl -i http://localhost:3000/
curl -i http://localhost:3000/missing

Check it worked

The first terminal prints Listening on http://localhost:3000/. The first curl shows HTTP/1.1 200 OK, a content-type header of text/html; charset=utf-8 (curl may show the header name in lower case) and the body <h1>Hello, web</h1>. The second shows HTTP/1.1 404 Not Found and Not found. Open http://localhost:3000/ in a browser on the same computer to see the heading. Press Ctrl+C in the first terminal to stop the server.

Step 6 · Test the greet function with bun test

bun test finds files whose names end in .test.ts (or .test.js, .spec.ts and similar) and runs them. Write one test file:

Bash
cat > greet.test.ts <<'TS'
import { expect, test } from "bun:test";
import { greet } from "./greet.ts";

test("greets by name", () => {
  expect(greet("Ada")).toBe("Hello, Ada");
});

test("keeps accented letters", () => {
  expect(greet("Ọlá")).toBe("Hello, Ọlá");
});
TS
bun test
  • bun:test is a module built into Bun, so there is nothing to install. Its test and expect work like Jest's.
  • test("greets by name", () => { ... }) names a test and gives the code to run.
  • expect(value).toBe(expected) fails the test if the two values differ.
  • The second test checks that text outside plain English letters passes through unchanged, which matters as soon as real people type their names into your program.

Check it worked

The output lists greet.test.ts with a tick next to each test name, then 2 pass and 0 fail. To see a failure, change "Hello, Ada" to "Hi, Ada" and run bun test again: it marks that test as failed, prints the expected and received values and exits with a non-zero status. Change it back.

Step 7 · Compile the program into one executable

bun build --compile bundles index.ts, everything it imports and a copy of the Bun runtime into a single file:

Bash
bun build ./index.ts --compile --outfile hello
ls -lh hello
./hello Ada
env PATH=/usr/bin:/bin ./hello Ada
  • ./index.ts is the entry point. Bun follows its import to include greet.ts.
  • --compile asks for an executable instead of a JavaScript bundle.
  • --outfile hello names the result.
  • The last line runs the binary with a PATH that does not contain Bun, to show the file does not need Bun installed.

The file is large, tens of megabytes, because the whole runtime is inside it. It runs on the same operating system and processor type it was built on. To build for another one, add a target, for example --target=bun-linux-x64 for most Linux servers.

Check it worked

ls -lh shows hello with a size in megabytes. Both ./hello Ada runs print Hello, Ada and Running on Bun 1.4.4. Copy hello to another machine with the same system and processor and it runs there without Bun.

Step 8 · Review common mistakes, check Node.js compatibility, then clean up

These are the problems people hit most in their first week with Bun:

  • bun: command not found after installing. The installer changed your shell's start-up file, which only new terminals read. Open a new terminal or run the two export lines from step 1.
  • Thinking bun index.ts checked your types. It only strips them. Run bun check, or bun run typecheck, which bun init set up to do the same.
  • Expecting every Node.js package to work unchanged. Most do. Before you move an existing Node.js project, read Bun's Node.js compatibility page, which marks each built-in module (node:fs, node:http and so on) as fully, partly or not yet implemented, then run the project's own test suite with Bun.
  • Using the Bun global in code that must also run on Node.js. Bun.serve, Bun.argv and bun:test exist only in Bun. Code that should run on both sticks to process.argv, node: modules and web-standard APIs such as fetch.
  • Committing node_modules. The .gitignore from bun init already leaves it out; commit bun.lock instead, so everyone installs the same versions.

Then delete the project folder:

Bash
cd ~
rm -rf ~/hello-bun

That removes the code, the binary and node_modules. To remove Bun itself on Linux or macOS, delete ~/.bun with rm -rf ~/.bun, which also deletes the package cache, and remove the two BUN_INSTALL lines from ~/.bashrc or ~/.zshrc. In WSL, the same commands apply.

Check it worked

ls ~/hello-bun reports No such file or directory. bun --version still prints 1.4.4 unless you removed Bun too.

Next steps

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.