Quickstart
Build your first app with Bun
Overview
Build a minimal HTTP server with Bun.serve, run it locally, then evolve it by installing a package.
PATH. See installation for setup.Step 1
Initialize a new project with bun init.
$ bun init my-appIt'll prompt you to pick a template, either Blank, React, or Library. For this guide, we'll pick Blank.
$ 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 autocomplete)
- README.mdThis automatically creates a my-app directory with a basic Bun app.
Step 2
Run the index.ts file using bun run index.ts.
$ cd my-app
$ bun run index.ts
Hello via Bun!You should see a console output saying "Hello via Bun!".
Step 3
Replace the contents of index.ts with the following code:
const server = Bun.serve({
port: 3000,
routes: {
"/": () => new Response('Bun!'),
}
});
console.log(`Listening on ${server.url}`);Run the index.ts file again using bun run index.ts.
$ bun run index.ts
Listening on http://localhost:3000Visit http://localhost:3000 to test the server. You should see a simple page that says "Bun!".
Step 4
Install the figlet package and its type declarations. Figlet is a utility for converting strings into ASCII art.
$ bun add figlet
$ bun add -d @types/figlet # TypeScript users onlyUpdate index.ts to use figlet in routes.
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 index.ts file again using bun run index.ts.
$ bun run index.ts
Listening on http://localhost:3000Visit http://localhost:3000/figlet to test the server. You should see a simple page that says "Bun!" in ASCII art.
____ _
| __ ) _ _ _ __ | |
| _ \| | | | '_ \| |
| |_) | |_| | | | |_|
|____/ \__,_|_| |_(_)Step 5
Let's add some HTML. Create a new file called index.html and add the following code:
<!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.
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 index.ts file again using bun run index.ts.
$ bun run index.ts
Listening on http://localhost:3000Visit http://localhost:3000 to test the server. You should see the static HTML page.
🎉 Congratulations! You've built a simple HTTP server with Bun and installed a package.
Run a script
Bun can also execute "scripts" from your package.json. Add the following script:
{
"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.
$ bun run start
Listening on http://localhost:3000bun run is roughly 28x faster than npm run (6ms vs 170ms of overhead).