Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 39 ยท Getting Started

What Is Bun?

Learn what Bun is - a fast JavaScript and TypeScript runtime with a package manager, bundler and test runner built in - how it works, and when to choose it over Node.js.

Bun is a JavaScript and TypeScript runtime: a program that runs your .js, .ts, .jsx and .tsx files outside the browser, the same job Node.js does. What makes Bun different is that it ships as one executable that also contains a package manager, a bundler, a test runner and a transpiler. Instead of installing Node, npm, a TypeScript compiler, a bundler such as esbuild and a test framework, you install Bun once and get all of them.

This course takes you from the first bun --version to servers, tests, databases and deployment. In this first lesson you get the big picture: what Bun is made of, why it is quick, and how to decide whether it belongs in your project.

Bun is not available in the in-page runners of this site. Bun code in this course appears in read-only blocks, and where a lesson needs something you can run in the browser, it uses a clearly labelled Node.js stand-in that shows the same idea with standard APIs.

The toolbox in one binary

A typical JavaScript project today pulls in many separate tools. Bun folds the common ones into a single command:

One binary, four jobs

Runtime bun run runs JS and TS files
Package manager bun install and bun add
Bundler bun build packs your code
Test runner bun test, Jest-style

All four share the same engine and the same configuration.

1 / 2

Because they live in one program, they cooperate. The test runner understands TypeScript without a build step, the package manager and runtime share one cache, and the bundler uses the same transpiler as the runtime.

How Bun is built

Bun is written mostly in Zig, a low-level systems language, and uses JavaScriptCore (JSC) as its JavaScript engine. JavaScriptCore is the engine of Safari. Node.js and Chrome use a different engine, V8. Engines differ in start-up time and memory use: JavaScriptCore tends to start faster and use less memory for short scripts, which is a big part of Bun's reputation for speed.

Many of the things you would normally get from npm packages are written natively in Zig and exposed as Bun APIs. Parsing TypeScript, resolving modules, installing packages and hashing passwords are all done by compiled code, not by JavaScript running on top of the runtime. That is why bun install is usually much faster than npm install and why running a TypeScript file feels instant.

flowchart LR
  A["Your code<br/>.ts .tsx .js"] --> B["Bun transpiler<br/>(native, Zig)"]
  B --> C["JavaScriptCore<br/>engine"]
  C --> D["Bun APIs<br/>serve, file, sqlite"]
  C --> E["Node.js-compatible<br/>modules: fs, path, http"]

Your file is transpiled natively, then executed by JavaScriptCore, which can call Bun's own APIs or the Node.js-compatible modules.

Drop-in for Node.js, mostly

Bun aims to be a drop-in replacement for Node.js. It implements most of the Node.js standard library (node:fs, node:path, node:http, node:crypto and many more), understands package.json, reads node_modules, and supports both ES modules and CommonJS. A large share of npm packages, including popular frameworks such as Express, Hono, Next.js and Vite, run on Bun unchanged.

"Mostly" matters. Some Node.js internals, rarely used modules, native add-ons and edge-case behaviours differ. The Deploy and Compatibility chapter covers this in depth. For now remember the rule of thumb: try your project on Bun, run its tests, and see.

Web standards first

Bun leans on the web platform. fetch, Request, Response, Headers, URL, ReadableStream, WebSocket, TextEncoder, crypto.subtle, Blob and FormData are all globals, with no import. If you know how to write code for the browser or for a service worker, you already know much of what Bun expects. Its HTTP server, for example, takes a function that receives a standard Request and returns a standard Response.

Here is a Node.js stand-in that shows that style: a handler written only with web-standard objects. Bun's Bun.serve accepts exactly this kind of function.

Node.js Stand-in: a web-standard request handler (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.

In real Bun the handler would be wrapped like this (read-only):

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

Where Bun shines, and where to be careful

Bun is a strong choice when:

  • you want fast installs and fast scripts, for example in CI where install time is paid on every run;
  • you write TypeScript and do not want a separate compile step;
  • you build small HTTP services, scripts and CLI tools, especially with the built-in SQLite and file APIs;
  • you want one tool to replace several dev dependencies.

Think twice when:

  • your app depends on native Node add-ons or very Node-specific internals;
  • your hosting platform only supports a particular Node.js version;
  • your team relies on tooling that expects exactly Node's behaviour.

A common, low-risk path is to use Bun only as a package manager and test runner first, while the app still runs on Node, and move the runtime over later. The course returns to that idea in the package manager chapter.

Versions and release channel

Bun releases frequently. bun --version prints the version and bun upgrade updates it in place. Features described in this course target the Bun 1.x line; the project is stable for production use, but new APIs appear in minor releases, so check the release notes when something is missing. The very first lesson that touches your machine is next: installing Bun.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which JavaScript engine does Bun use?

    Bun embeds JavaScriptCore, the engine from Safari. Node.js and Chrome use V8.
  2. 2. Which of these is NOT built into the bun executable?

    Bun bundles a runtime, package manager, bundler, transpiler and test runner, but not a browser.
  3. 3. What does "drop-in replacement for Node.js" mean for Bun?

    Bun implements most of the Node.js API and reads node_modules, but a few modules and native add-ons behave differently or are missing.
  4. 4. What does the function you pass as fetch to Bun.serve receive and return?

    Bun's server uses web-standard Request and Response objects.

Summary

  • Bun is a JavaScript and TypeScript runtime with a package manager, bundler, transpiler and test runner in one executable.
  • It is written in Zig and uses the JavaScriptCore engine, which helps start-up time and memory use.
  • It targets Node.js compatibility and embraces web standards such as fetch, Request and Response.
  • It is a good fit for fast installs, TypeScript projects and small services; check compatibility for native add-ons.
  • Bun APIs in this course are shown read-only, with labelled Node.js stand-ins where you can run something.

Next: Installing Bun