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:
sudo apt update
sudo apt install -y curl unzipThen 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:
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:
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
bun --version
command -v bunA 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:
mkdir -p ~/hello-bun
cd ~/hello-bun
bun init -y
ls -abun 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 atypecheckscript. Bun reads the samepackage.jsonformat 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 bybun check.README.mdand.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:
cat > greet.ts <<'TS'
export function greet(name: string): string {
return `Hello, ${name}`;
}
TSexportmakes the function available to other files. Without it,greetwould be private togreet.ts.function greet(name: string): string {declares a function that takes one argument.name: stringis a TypeScript type annotation: callers must pass text. The: stringafter 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:
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 Adaimport { greet } from "./greet.ts";loads the function from the other file. Bun accepts the.tsextension in the path.Bun.argvis the list of words on the command line. Item 0 is the path tobun, 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]isundefined, sonamebecomes"world".Bunis a global object that only exists in Bun.Bun.versionis 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:
bun checkCheck 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:
bun add express@5.3.0Now 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.
rm -rf node_modules bun.lock
time npm install
rm -rf node_modules package-lock.json
bun pm cache rm
time bun installCheck 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:
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}`);
TSBun.serve({ ... })starts the server and returns an object describing it.port: 3000is the port to listen on. Pick another number if something already uses 3000.fetch(req)runs once for every request and must return aResponse.RequestandResponseare the same web-standard classes browsers use forfetch().new URL(req.url)splits the address into parts, sourl.pathnameis the path, such as/.- The home page gets an HTML heading with a
Content-Typeheader.charset=utf-8tells 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 foundwith status 404.
Start it. The server keeps running in this terminal until you press Ctrl+C:
bun server.tsIn a second terminal, request both paths:
curl -i http://localhost:3000/
curl -i http://localhost:3000/missingCheck 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:
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 testbun:testis a module built into Bun, so there is nothing to install. Itstestandexpectwork 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:
bun build ./index.ts --compile --outfile hello
ls -lh hello
./hello Ada
env PATH=/usr/bin:/bin ./hello Ada./index.tsis the entry point. Bun follows itsimportto includegreet.ts.--compileasks for an executable instead of a JavaScript bundle.--outfile hellonames the result.- The last line runs the binary with a
PATHthat 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 foundafter installing. The installer changed your shell's start-up file, which only new terminals read. Open a new terminal or run the twoexportlines from step 1.- Thinking
bun index.tschecked your types. It only strips them. Runbun check, orbun run typecheck, whichbun initset 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:httpand so on) as fully, partly or not yet implemented, then run the project's own test suite with Bun. - Using the
Bunglobal in code that must also run on Node.js.Bun.serve,Bun.argvandbun:testexist only in Bun. Code that should run on both sticks toprocess.argv,node:modules and web-standard APIs such asfetch. - Committing
node_modules. The.gitignorefrombun initalready leaves it out; commitbun.lockinstead, so everyone installs the same versions.
Then delete the project folder:
cd ~
rm -rf ~/hello-bunThat 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
- Compare a runtime that also runs TypeScript directly but takes a permissions-first approach: Hello World in Deno.
- See the same first program in plain JavaScript on Node.js: Hello World in JavaScript.
- Build a real HTTP API with routes and JSON (it runs under Bun too): Build a REST API with Express 5.
Related tutorials
- Hello World in Zig: zig run, zig build and zig ccYou will install a signature-checked Zig 0.17.1 on Ubuntu 26.04, write and run Hello World with the current I/O API, build a small project with zig build that handles errors explicitly, and use zig cc to compile a C program for Linux and for Windows.
- Hello World in x86-64 assembly with NASM and Linux system callsYou will write an x86-64 assembly program that prints a line using only Linux system calls, assemble it with NASM, link it with ld, check its exit status, then loop it three times and read its machine code with objdump.
- Hello World in WebAssembly text format with wabt and WasmtimeYou will write a WebAssembly module by hand in the text format, assemble it with wat2wasm, print Hello World through WASI in Wasmtime 50, and call an exported add function from both Wasmtime and Node.js.
Need this done for you?
Padding does this work for growing companies, from the first diagnosis to a system that keeps working.
Get new tutorials