Skip to main content

​
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.
1

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.
2

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.
3

Step 3

Replace the contents of index.ts with the following code:
https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/typescript.svgindex.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!".
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
  }
}
4

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.
https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/typescript.svgindex.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.
____              _
| __ ) _   _ _ __ | |
|  _ \| | | | '_ \| |
| |_) | |_| | | | |_|
|____/ \__,_|_| |_(_)
5

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 /.
https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/typescript.svgindex.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:
https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/typescript.svgindex.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:
https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/typescript.svgbuild.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.

Build docs developers (and LLMs) love

Get started for freeTalk to us