> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zhcndoc/bun/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Build your first app with Bun

## Overview

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

<Info>Prerequisites: Bun is installed and available in your `PATH`. For installation, see [Installation](/installation).</Info>

***

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

    ```bash terminal icon="terminal" theme={null}
    bun init my-app
    ```

    It will prompt you to select a template—either `Blank`, `React`, or `Library`. For this guide, we'll choose `Blank`.

    ```bash terminal icon="terminal" theme={null}
    bun init my-app
    ```

    ```txt theme={null}
    ✓ 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.
  </Step>

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

    ```bash terminal icon="terminal" theme={null}
    cd my-app
    bun run index.ts
    ```

    ```txt theme={null}
    Hello via Bun!
    ```

    You should see `"Hello via Bun!"` printed to the console.
  </Step>

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

    ```ts index.ts icon="https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/typescript.svg" theme={null}
    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`.

    ```bash terminal icon="terminal" theme={null}
    bun run index.ts
    ```

    ```txt theme={null}
    Listening on http://localhost:3000
    ```

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

    <Accordion title="Seeing TypeScript errors in 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.

      ```bash terminal icon="terminal" theme={null}
      bun add -d @types/bun
      ```

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

      ```json tsconfig.json icon="file-json" theme={null}
      {
        "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 that converts strings to ASCII art.

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

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

    ```ts index.ts icon="https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/typescript.svg" theme={null}
    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 the file again with `bun run index.ts`.

    ```bash terminal icon="terminal" theme={null}
    bun run index.ts
    ```

    ```txt theme={null}
    Listening on http://localhost:3000
    ```

    Visit [`http://localhost:3000/figlet`](http://localhost:3000/figlet) to test the server. You should see `"Bun!"` displayed as ASCII art.

    ```txt theme={null}
    ____              _
    | __ ) _   _ _ __ | |
    |  _ \| | | | '_ \| |
    | |_) | |_| | | | |_|
    |____/ \__,_|_| |_(_)
    ```
  </Step>

  <Step title="Step 5">
    Let's add some HTML. Create a new file `index.html` and add the following code:

    ```html index.html icon="file-code" theme={null}
    <!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="https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/typescript.svg" theme={null}
    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 the file again with `bun run index.ts`.

    ```bash terminal icon="terminal" theme={null}
    bun run index.ts
    ```

    ```txt theme={null}
    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>

🎉 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:

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

Then run it with `bun run start`.

```bash terminal icon="terminal" theme={null}
bun run start
```

```txt theme={null}
Listening on http://localhost:3000
```

<Note>⚡️ **Performance** — `bun run` is approximately 28x faster than `npm run` (6ms vs 170ms of overhead).</Note>

***

## Watch mode

Use the `--watch` flag to automatically restart the process when any imported file changes:

```bash terminal icon="terminal" theme={null}
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:

```bash terminal icon="terminal" theme={null}
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:

```bash terminal icon="terminal" theme={null}
bun install
```

To add a specific package:

```bash terminal icon="terminal" theme={null}
bun add <package>
```

To add a dev dependency:

```bash terminal icon="terminal" theme={null}
bun add -d <package>
```

***

## Run tests

Bun includes a fast, Jest-compatible test runner. Create a test file:

```ts index.test.ts icon="https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/typescript.svg" theme={null}
import { expect, test } from "bun:test";

test("2 + 2", () => {
  expect(2 + 2).toBe(4);
});
```

Run your tests:

```bash terminal icon="terminal" theme={null}
bun test
```

***

## Bundle for production

Bun can bundle your code for production with `Bun.build`:

```ts build.ts icon="https://mintlify.s3.us-west-1.amazonaws.com/zhcndoc-bun/icons/typescript.svg" theme={null}
await Bun.build({
  entrypoints: ['./index.ts'],
  outdir: './dist',
  minify: true,
  target: 'node',
});
```

Or use the CLI:

```bash terminal icon="terminal" theme={null}
bun build ./index.ts --outdir ./dist --minify
```

***

## Next steps

<CardGroup cols={2}>
  <Card icon="book-open" title="Runtime" href="/runtime">
    Learn about Bun's JavaScript runtime, including TypeScript support, JSX, and Web APIs.
  </Card>

  <Card icon="box" title="Package Manager" href="/pm/cli/install">
    Explore Bun's fast package manager with workspaces and global cache.
  </Card>

  <Card icon="flask-conical" title="Test Runner" href="/test">
    Write and run tests with Bun's Jest-compatible test runner.
  </Card>

  <Card icon="combine" title="Bundler" href="/bundler">
    Bundle TypeScript, JSX, and CSS for the browser or server.
  </Card>
</CardGroup>