Quickstart

Let's write a simple HTTP server using the built-in Bun.serve API. First, create a fresh directory.

mkdir quickstart

cd quickstart

Run bun init to scaffold a new project. It's an interactive tool; for this tutorial, just press enter to accept the default answer for each prompt.

bun init

bun init helps you get started with a minimal project and tries to
guess sensible defaults. Press ^C anytime to quit.

package name (quickstart):
entry point (index.ts):

Done! A package.json file was saved in the current directory.
 + index.ts
 + .gitignore
 + tsconfig.json (for editor auto-complete)
 + README.md

To get started, run:
  bun run index.ts

Since our entry point is a *.ts file, Bun generates a tsconfig.json for you. If you're using plain JavaScript, it will generate a jsconfig.json instead.

Run a file

Open index.ts and paste the following code snippet, which implements a simple HTTP server with Bun.serve.

const server = Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Bun!");
  },
});

console.log(`Listening on http://localhost:${server.port} ...`);

bun add -d @types/bun

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

Run the file from your shell.

bun index.ts

Listening on http://localhost:3000 ...

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

Run a script

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

{
  "name": "quickstart",
  "module": "index.ts",
  "type": "module",
  "scripts": {
    "start": "bun run index.ts"
  },
  "devDependencies": {
    "@types/bun": "^1.0.0"
  }
}

Then run it with bun run start.

bun run start

  $ bun run index.ts
  Listening on http://localhost:3000 ...

Install a package

Let's make our server a little more interesting by installing a package. First 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 only

Update index.ts to use figlet in the fetch handler.

import figlet from "figlet";

const server = Bun.serve({
  port: 3000,
  fetch(req) {
    const body = figlet.textSync("Bun!");
    return new Response(body);
    return new Response("Bun!");
  },
});

Restart the server and refresh the page. You should see a new ASCII art banner.

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