# Quickstart (/docs/quickstart)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1454 · updated: 2026-07-28 -->
Related: [Welcome to Bun](/docs/index.md), [Installation](/docs/installation.md), [TypeScript](/docs/typescript.md), [TypeScript 6 and 7](/docs/typescript-6.md), [Feedback](/docs/feedback.md)

## Overview [#overview]

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

<Info>
  Prerequisites: Bun installed and available on your 

  `PATH`

  . See 

  [installation](/installation)

   for setup.
</Info>

***

<Steps>
  <Step title="Step 1">
    Initialize a new project with `bun init`.

    ```bash terminal icon="terminal"
    bun init my-app
    ```

    `bun init` prompts you to pick a template: `Blank`, `React`, or `Library`. For this guide, pick `Blank`.

    ```bash terminal icon="terminal"
    bun init my-app
    ```

    ```txt
    ✓ 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.md
    ```

    The new `my-app` directory contains a basic Bun app.
  </Step>

  <Step title="Step 2">
    Run `index.ts` with `bun run`.

    ```bash terminal icon="terminal"
    cd my-app
    bun run index.ts
    ```

    ```txt
    Hello via Bun!
    ```
  </Step>

  <Step title="Step 3">
    Replace the contents of `index.ts` with the following code:

    ```ts index.ts icon="/icons/typescript.svg"
    const server = Bun.serve({
      port: 3000,
      routes: {
        "/": () => new Response('Bun!'),
      }
    });

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

    Run `index.ts` again.

    ```bash terminal icon="terminal"
    bun run index.ts
    ```

    ```txt
    Listening on http://localhost:3000/
    ```

    Visit [`http://localhost:3000`](http://localhost:3000) to test the server. You should see a page that says `"Bun!"`.

    <Accordion title="Seeing TypeScript errors on Bun?">
      `bun init` installs Bun's TypeScript declarations and configures your `tsconfig.json`. If you're trying out Bun in an existing project, you may see a type error on the `Bun` global.

      To fix this, first install `@types/bun` as a dev dependency.

      ```bash terminal icon="terminal"
      bun add -d @types/bun
      ```

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

      ```json tsconfig.json icon="file-json"
      {
        "compilerOptions": {
          "lib": ["ESNext"],
          "target": "ESNext",
          "module": "Preserve",
          "moduleDetection": "force",
          "moduleResolution": "bundler",
          "allowImportingTsExtensions": true,
          "verbatimModuleSyntax": true,
          "noEmit": true
        }
      }
      ```
    </Accordion>
  </Step>

  <Step title="Step 4">
    Install the `figlet` package and its type declarations. Figlet is a utility for converting strings into ASCII art.

    ```bash terminal icon="terminal"
    bun add figlet
    bun add -d @types/figlet # TypeScript users only
    ```

    Update `index.ts` to use `figlet` in `routes`.

    ```ts index.ts icon="/icons/typescript.svg"
    import figlet from 'figlet'; // [!code ++]

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

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

    Run `index.ts` again.

    ```bash terminal icon="terminal"
    bun run index.ts
    ```

    ```txt
    Listening on http://localhost:3000/
    ```

    Visit [`http://localhost:3000/figlet`](http://localhost:3000/figlet) to test the server. You should see a page that says `"Bun!"` in ASCII art.

    ```txt
    ____              _
    | __ ) _   _ _ __ | |
    |  _ \| | | | '_ \| |
    | |_) | |_| | | | |_|
    |____/ \__,_|_| |_(_)
    ```
  </Step>

  <Step title="Step 5">
    Now add some HTML. Create a new file called `index.html`:

    ```html index.html icon="file-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.

    ```ts index.ts icon="/icons/typescript.svg"
    import figlet from 'figlet';
    import index from './index.html'; // [!code ++]

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

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

    Run `index.ts` again.

    ```bash terminal icon="terminal"
    bun run index.ts
    ```

    ```txt
    Listening on http://localhost:3000/
    ```

    Visit [`http://localhost:3000`](http://localhost:3000) to test the server. You should see the static HTML page.
  </Step>
</Steps>

You've built an HTTP server with Bun and installed a package.

***

## Run a script [#run-a-script]

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

{/* prettier-ignore */}

```json package.json icon="file-json"
{
  "name": "my-app",
  "module": "index.ts",
  "type": "module",
  "private": true,
  "scripts": { // [!code ++]
    "start": "bun run index.ts" // [!code ++]
  }, // [!code ++]
  "devDependencies": {
    "@types/bun": "latest"
  },
  "peerDependencies": {
    "typescript": "^6"
  }
}
```

Then run it with `bun run start`.

```bash terminal icon="terminal"
bun run start
```

```txt
Listening on http://localhost:3000/
```

<Note>
  ⚡️ 

  **Performance**

   — 

  `bun run`

   is roughly 28x faster than 

  `npm run`

   (6ms vs 170ms of overhead).
</Note>