Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 39 ยท Getting Started

Your First Bun Program

Create a project with bun init, understand every generated file, run TypeScript with bun run, read command-line arguments and print output - your first complete Bun program.

With Bun installed, it is time to write and run code. In this lesson you will create a project with bun init, look at each file it generates, run a TypeScript file directly, pass arguments to it, and build a small but real command-line program. Everything here works the same on Windows, macOS and Linux.

Code in this lesson is shown in read-only blocks because the page cannot run Bun. Where it helps, a Node.js stand-in lets you try the logic.

Create a project with bun init

Make an empty folder and initialise it:

Terminal
mkdir hello-bun
cd hello-bun
bun init

bun init asks a few questions: the package name, the entry point (default index.ts) and, in newer versions, the kind of project (blank, React, library). Press Enter to accept the defaults, or skip the questions with bun init -y. The result is a small folder:

TEXT
hello-bun/
โ”œโ”€โ”€ .gitignore
โ”œโ”€โ”€ README.md
โ”œโ”€โ”€ bun.lock
โ”œโ”€โ”€ index.ts
โ”œโ”€โ”€ node_modules/
โ”œโ”€โ”€ package.json
โ””โ”€โ”€ tsconfig.json

Exact files vary a little between versions, but these are the usual ones:

File What it is
index.ts Your entry point. It starts with a single console.log("Hello via Bun!").
package.json Project metadata, scripts and dependencies. Includes "type": "module".
tsconfig.json TypeScript settings so editors understand your code.
bun.lock The lockfile (appears once dependencies exist or are installed).
.gitignore Ignores node_modules and similar.
node_modules/ Holds @types/bun, so the editor knows the Bun global.

Run it

Terminal
bun run index.ts

The output is Hello via Bun!. Notice what did not happen: you did not compile TypeScript, install ts-node, or configure anything. Bun transpiles .ts in memory, then runs the result.

The run word is optional when the argument is a file:

Terminal
bun index.ts

Both forms do the same thing. Use bun run when you want to be explicit; it is also the form that runs package.json scripts, covered in Scripts and bunx.

Edit the program

Replace index.ts with something that has types and a function:

TypeScript
type Greeting = {
  name: string;
  excited: boolean;
};

function greet({ name, excited }: Greeting): string {
  return excited ? `Hello, ${name}!` : `Hello, ${name}.`;
}

console.log(greet({ name: "Ada", excited: true }));
console.log(`Running on Bun ${Bun.version}`);

Run it with bun index.ts. The first line prints Hello, Ada!. The second uses the Bun global, which exists only on Bun, and prints your installed version.

Two important facts about TypeScript in Bun:

  • Types are erased, not checked. Bun removes the annotations and runs the JavaScript. A wrong type will not stop the program. Run bunx tsc --noEmit (or let your editor do it) when you want real type checking.
  • No await restrictions. Top-level await works in any module, so a script can simply await fetch(...) at the top.

Command-line arguments

Anything after the file name is passed to your program. Bun.argv is an array with the runtime path first, the script path second, then your arguments. process.argv has the same shape, because Bun is Node-compatible.

TypeScript
// greet.ts
const args = Bun.argv.slice(2);
const name = args[0] ?? "world";
console.log(`Hello, ${name}!`);
Terminal
bun greet.ts Grace

That prints Hello, Grace!. A flag such as --shout is just another string in the array. For anything more than a couple of arguments, use Node's built-in parser, which Bun supports:

TypeScript
import { parseArgs } from "node:util";

const { values, positionals } = parseArgs({
  args: Bun.argv.slice(2),
  options: {
    shout: { type: "boolean", short: "s" },
    times: { type: "string", default: "1" },
  },
  allowPositionals: true,
});

const name = positionals[0] ?? "world";
const line = values.shout ? `HELLO, ${name.toUpperCase()}!` : `Hello, ${name}.`;
for (let i = 0; i < Number(values.times); i++) {
  console.log(line);
}

bun greet.ts Ada --shout --times 2 prints the shouted line twice.

Try the same logic on Node

The argument-parsing code uses only node:util, so it runs anywhere. This stand-in feeds the parser a fixed array instead of reading the command line, so you can experiment with the options:

Node.js Stand-in: parseArgs with a fixed argument list (runs on Node 24)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Try changing fakeArgs to ['Grace'] or ['-s'].

Reading input and finishing cleanly

A program ends when there is nothing left to do. To end early with a status code, set process.exitCode or call process.exit(code). Exit code 0 means success; anything else means failure, which shell scripts and CI use.

TypeScript
const input = Bun.argv[2];
if (!input) {
  console.error("Usage: bun run greet.ts <name>");
  process.exit(1);
}

To read a line from the user, prompt() (a browser global that Bun also provides) works:

TypeScript
const answer = prompt("What is your name?");
console.log(`Nice to meet you, ${answer}.`);

For piped input, read the standard input stream:

TypeScript
const text = await Bun.stdin.text();
console.log(`You typed ${text.length} characters.`);

echo "hello" | bun read.ts prints You typed 6 characters. (five letters plus the newline).

Uncaught errors look different

If your code throws, Bun prints the error with the source line and a caret pointing at the problem, then exits with a non-zero code. Because it transpiled your TypeScript, line numbers still match your original file thanks to source maps.

Node.js Stand-in: an uncaught error and exit code (runs on Node 24)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Your project folder in practice

A few habits that pay off from day one:

  • Commit bun.lock to git so everyone installs the same versions.
  • Keep source in src/ once you have more than one file, and point index.ts at it.
  • Add scripts to package.json ("dev": "bun --watch src/index.ts") so commands are memorable.
  • Never commit node_modules.

You will meet each of these again; the CLI tour lists every command you can run.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command creates a new Bun project?

    bun init scaffolds package.json, tsconfig.json, an entry file and more.
  2. 2. Does bun run index.ts type-check the file?

    Bun only strips types. Use an editor or tsc --noEmit for checking.
  3. 3. In Bun.argv, where do your own arguments start?

    Index 0 is the Bun executable, index 1 the script path; arguments you typed start at index 2.
  4. 4. What does an exit code of 0 mean?

    Zero is success; non-zero tells the shell or CI that something went wrong.

Summary

  • bun init creates package.json, tsconfig.json, index.ts and friends.
  • bun run file.ts (or bun file.ts) runs TypeScript directly, with no compile step.
  • Types are erased, not checked; use tsc --noEmit for checks.
  • Bun.argv.slice(2) holds your arguments; parseArgs from node:util parses flags.
  • Use process.exit(code) and standard input (Bun.stdin.text()) for scripts that behave like real tools.

Next: A Tour of the Bun CLI