Quickstart

Build a working HTTP server with Bun in under 5 minutes.

This guide walks you from zero to a running HTTP server. You’ll initialize a project, write a server using Bun.serve(), and run it — all without any compilation step.

You need Bun installed before starting. See Installation if you haven’t done that yet.

1. Create a new project

   Run bun init to scaffold a new project. Pass a directory name to create it in a subdirectory:

   bun init my-app
   

   Bun prompts you to choose a template. Select Blank for this guide:

   ✓ Select a project template: Blank
   
   - .gitignore
   - index.ts
   - tsconfig.json (for editor autocomplete)
   - README.md
   

   This creates a my-app/ directory with a minimal TypeScript project. The tsconfig.json is configured for Bun and includes type definitions automatically.

2. Run the default file

   Move into the project directory and run the generated index.ts:

   cd my-app
   bun run index.ts
   

   Hello via Bun!
   

   Bun executes TypeScript directly — no compilation step, no tsc, no build output.

3. Write an HTTP server

   Replace the contents of index.ts with a simple HTTP server using Bun.serve():

   index.ts

   const server = Bun.serve({
     port: 3000,
     fetch(req) {
       return new Response("Hello from Bun!");
     },
   });
   
   console.log(`Listening on http://localhost:${server.port}`);
   

   Run it:

   bun run index.ts
   

   Listening on http://localhost:3000
   

   Open http://localhost:3000 in your browser. You should see Hello from Bun!.

   Bun.serve() accepts a fetch handler that receives a standard Request and must return a Response. These are the same Web APIs used in service workers and edge runtimes.

4. Add routing

   Bun.serve() also supports a routes object for declarative routing without a framework:

   index.ts

   const server = Bun.serve({
     port: 3000,
     routes: {
       "/": () => new Response("Hello from Bun!"),
       "/health": () => new Response("OK"),
     },
     fetch(req) {
       // fallback for unmatched routes
       return new Response("Not found", { status: 404 });
     },
   });
   
   console.log(`Listening on http://localhost:${server.port}`);
   

   Run it again and visit http://localhost:3000/health.

5. Add a package.json script

   Open package.json and add a start script so you can run the server with a short command:

   package.json

   {
     "name": "my-app",
     "module": "index.ts",
     "type": "module",
     "scripts": {
       "start": "bun run index.ts"
     },
     "devDependencies": {
       "@types/bun": "latest"
     }
   }
   

   Now start the server with:

   bun run start
   

   bun run is roughly 28x faster than npm run — 6ms vs 170ms of overhead per invocation. For projects with many scripts, this adds up quickly.

You now have a working Bun HTTP server. Here are some natural next steps:

TypeScript

Learn how Bun handles TypeScript natively, including recommended tsconfig settings.

HTTP server API

Explore the full Bun.serve() API: WebSockets, TLS, streaming responses, and more.

Package manager

Install npm packages with bun add and manage dependencies faster than npm.

Test runner

Write and run Jest-compatible tests with bun test.