Quickstart

Overview

Build a minimal HTTP server with Bun.serve, run it locally, then extend it by installing a package.

Prerequisites: Bun is installed and available in your PATH. For installation, see Installation.

Step 1

Initialize a new project with bun init.

terminal

bun init my-app

It will prompt you to select a template—either Blank, React, or Library. For this guide, we’ll choose Blank.

terminal

bun init my-app

✓ Select a project template: Blank

- .gitignore
- CLAUDE.md
- .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc -> CLAUDE.md
- index.ts
- tsconfig.json (for editor auto-complete)
- README.md

This will automatically create a my-app directory with a basic Bun application.

Step 2

Run the index.ts file with bun run index.ts.

terminal

cd my-app
bun run index.ts

Hello via Bun!

You should see "Hello via Bun!" printed to the console.

Step 3

Replace the contents of index.ts with the following code:

index.ts

const server = Bun.serve({
  port: 3000,
  routes: {
    "/": () => new Response('Bun!'),
  }
});

console.log(`Listening on ${server.url}`);

Run the file again with bun run index.ts.

terminal

bun run index.ts

Listening on http://localhost:3000

Visit http://localhost:3000 to test the server. You should see a simple page displaying "Bun!".

Seeing TypeScript errors in Bun?

If you used bun init, Bun automatically installs Bun’s TypeScript declarations and configures your tsconfig.json. If you’re trying Bun in an existing project, you may see type errors for the Bun global.To fix this, first install @types/bun as a dev dependency.

terminal

bun add -d @types/bun

Then add the following to your tsconfig.json in the compilerOptions:

tsconfig.json

{
  "compilerOptions": {
    "lib": ["ESNext"],
    "target": "ESNext",
    "module": "Preserve",
    "moduleDetection": "force",
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "noEmit": true
  }
}

Step 4

Install the figlet package and its type declarations. Figlet is a utility that converts strings to ASCII art.

terminal

bun add figlet
bun add -d @types/figlet # TypeScript users only

Update index.ts to use figlet in the routes.

index.ts

import figlet from 'figlet'; 

const server = Bun.serve({
  port: 3000,
  routes: {
    "/": () => new Response('Bun!'),
    "/figlet": () => { 
      const body = figlet.textSync('Bun!'); 
      return new Response(body); 
    } 
  }
});

console.log(`Listening on ${server.url}`);

Run the file again with bun run index.ts.

terminal

bun run index.ts

Listening on http://localhost:3000

Visit http://localhost:3000/figlet to test the server. You should see "Bun!" displayed as ASCII art.

____              _
| __ ) _   _ _ __ | |
|  _ \| | | | '_ \| |
| |_) | |_| | | | |_|
|____/ \__,_|_| |_(_)

Step 5

Let’s add some HTML. Create a new file index.html and add the following code:

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Bun</title>
  </head>
  <body>
    <h1>Bun!</h1>
  </body>
</html>

Then import this file in index.ts and serve it from the root route /.

index.ts

import figlet from 'figlet';
import index from './index.html'; 

const server = Bun.serve({
  port: 3000,
  routes: {
    "/": index, 
    "/figlet": () => {
      const body = figlet.textSync('Bun!');
      return new Response(body);
    }
  }
});

console.log(`Listening on ${server.url}`);

Run the file again with bun run index.ts.

terminal

bun run index.ts

Listening on http://localhost:3000

Visit http://localhost:3000 to test the server. You should see the static HTML page.

🎉 Congratulations! You’ve successfully built a simple HTTP server with Bun and installed a package.

Run scripts

Bun can also execute "scripts" in package.json. Add the following script:

package.json

{
  "name": "quickstart",
  "module": "index.ts",
  "type": "module",
  "private": true,
  "scripts": { 
    "start": "bun run index.ts"
  }, 
  "devDependencies": {
    "@types/bun": "latest"
  },
  "peerDependencies": {
    "typescript": "^5"
  }
}

Then run it with bun run start.

terminal

bun run start

Listening on http://localhost:3000

⚡️ Performance — bun run is approximately 28x faster than npm run (6ms vs 170ms of overhead).

Watch mode

Use the --watch flag to automatically restart the process when any imported file changes:

terminal

bun --watch run index.ts

Now when you edit index.ts, Bun will automatically restart the server.

Hot reloading

For even faster development, use --hot mode, which reloads code without restarting the process:

terminal

bun --hot run index.ts

This preserves application state between reloads, making it ideal for development.

Install packages

Bun includes a fast, npm-compatible package manager. To install dependencies:

terminal

bun install

To add a specific package:

terminal

bun add <package>

To add a dev dependency:

terminal

bun add -d <package>

Run tests

Bun includes a fast, Jest-compatible test runner. Create a test file:

index.test.ts

import { expect, test } from "bun:test";

test("2 + 2", () => {
  expect(2 + 2).toBe(4);
});

Run your tests:

terminal

bun test

Bundle for production

Bun can bundle your code for production with Bun.build:

build.ts

await Bun.build({
  entrypoints: ['./index.ts'],
  outdir: './dist',
  minify: true,
  target: 'node',
});

Or use the CLI:

terminal

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

Next steps

Runtime

Learn about Bun’s JavaScript runtime, including TypeScript support, JSX, and Web APIs.

Package Manager

Explore Bun’s fast package manager with workspaces and global cache.

Test Runner

Write and run tests with Bun’s Jest-compatible test runner.

Bundler

Bundle TypeScript, JSX, and CSS for the browser or server.

​Overview

​Run scripts

​Watch mode

​Hot reloading

​Install packages

​Run tests

​Bundle for production

​Next steps

Runtime

Package Manager

Test Runner

Bundler

Overview

Run scripts

Watch mode

Hot reloading

Install packages

Run tests

Bundle for production

Next steps