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

# Bun

> Deploy Hono applications with Bun runtime

Bun is a fast all-in-one JavaScript runtime that includes a bundler, test runner, and package manager. Hono works seamlessly with Bun and takes advantage of its performance.

## Quick Start

Create a new Hono project for Bun:

```bash theme={null}
bun create hono my-app
```

Select "bun" as your template when prompted.

## Installation

Add Hono to your existing Bun project:

```bash theme={null}
bun add hono
```

## Basic Usage

Create your application in `index.ts`:

```typescript index.ts theme={null}
import { Hono } from 'hono'

const app = new Hono()

app.get('/', (c) => c.text('Hello Bun!'))

app.get('/api/hello', (c) => {
  return c.json({ message: 'Hello from Bun!' })
})

export default app
```

<Note>
  Bun automatically uses the `default` export as the fetch handler.
</Note>

## Running Your App

Run your Hono app with Bun:

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

Or use the development mode with hot reload:

```bash theme={null}
bun --hot run index.ts
```

## Adapter Features

The Bun adapter provides several utilities:

### Static Files

Serve static files from a directory:

```typescript theme={null}
import { Hono } from 'hono'
import { serveStatic } from 'hono/bun'

const app = new Hono()

app.use('/static/*', serveStatic({ root: './' }))
app.use('/favicon.ico', serveStatic({ path: './favicon.ico' }))

app.get('/', (c) => c.text('Hello!'))

export default app
```

### WebSocket Support

Bun has native WebSocket support. Use Hono's Bun adapter for WebSockets:

```typescript theme={null}
import { Hono } from 'hono'
import { createBunWebSocket } from 'hono/bun'

const app = new Hono()

const { upgradeWebSocket, websocket } = createBunWebSocket()

app.get(
  '/ws',
  upgradeWebSocket((c) => {
    return {
      onMessage(event, ws) {
        console.log(`Message from client: ${event.data}`)
        ws.send('Hello from server!')
      },
      onClose: () => {
        console.log('Connection closed')
      },
    }
  })
)

// Export with websocket handler
export default {
  port: 3000,
  fetch: app.fetch,
  websocket,
}
```

### Connection Info

Get connection information including IP address:

```typescript theme={null}
import { Hono } from 'hono'
import { getConnInfo } from 'hono/bun'

const app = new Hono()

app.get('/info', (c) => {
  const info = getConnInfo(c)
  return c.json({
    remote: info.remote,
  })
})

export default app
```

### Accessing Bun Server

Access the underlying Bun server instance:

```typescript theme={null}
import { Hono } from 'hono'
import { getBunServer } from 'hono/bun'
import type { Server } from 'bun'

const app = new Hono()

app.get('/server', (c) => {
  const server = getBunServer<Server>(c)
  
  return c.json({
    port: server?.port,
    hostname: server?.hostname,
  })
})

export default app
```

### Static Site Generation (SSG)

Generate static files from your Hono app:

```typescript theme={null}
import { Hono } from 'hono'
import { toSSG } from 'hono/bun'

const app = new Hono()

app.get('/', (c) => c.html('<h1>Home</h1>'))
app.get('/about', (c) => c.html('<h1>About</h1>'))

// Generate static files
toSSG(app, { dir: './dist' })
```

## Custom Server Configuration

Configure the Bun server with custom options:

```typescript index.ts theme={null}
import { Hono } from 'hono'

const app = new Hono()

app.get('/', (c) => c.text('Hello!'))

export default {
  port: 3000,
  hostname: '0.0.0.0',
  fetch: app.fetch,
  development: process.env.NODE_ENV !== 'production',
}
```

## Environment Variables

Bun loads `.env` files automatically:

```env .env theme={null}
API_KEY=your-secret-key
DATABASE_URL=postgres://localhost/mydb
```

Access environment variables:

```typescript theme={null}
import { Hono } from 'hono'

const app = new Hono()

app.get('/config', (c) => {
  return c.json({
    apiKey: process.env.API_KEY,
    dbUrl: process.env.DATABASE_URL,
  })
})

export default app
```

## Using Bun APIs

### File System

Use Bun's fast file system APIs:

```typescript theme={null}
import { Hono } from 'hono'

const app = new Hono()

app.get('/file/:name', async (c) => {
  const name = c.req.param('name')
  const file = Bun.file(`./files/${name}`)
  
  if (!(await file.exists())) {
    return c.notFound()
  }
  
  return c.body(await file.arrayBuffer())
})

export default app
```

### SQLite

Use Bun's built-in SQLite:

```typescript theme={null}
import { Hono } from 'hono'
import { Database } from 'bun:sqlite'

const app = new Hono()
const db = new Database('mydb.sqlite')

app.get('/users', (c) => {
  const users = db.query('SELECT * FROM users').all()
  return c.json(users)
})

app.post('/users', async (c) => {
  const body = await c.req.json()
  db.run('INSERT INTO users (name, email) VALUES (?, ?)', [body.name, body.email])
  return c.json({ message: 'User created' })
})

export default app
```

## Testing

Bun includes a built-in test runner:

```typescript index.test.ts theme={null}
import { expect, test } from 'bun:test'
import app from './index'

test('GET /', async () => {
  const res = await app.request('http://localhost/')
  expect(res.status).toBe(200)
  expect(await res.text()).toBe('Hello Bun!')
})

test('GET /api/hello', async () => {
  const res = await app.request('http://localhost/api/hello')
  expect(res.status).toBe(200)
  const json = await res.json()
  expect(json.message).toBe('Hello from Bun!')
})
```

Run tests:

```bash theme={null}
bun test
```

## Package Scripts

Set up scripts in `package.json`:

```json package.json theme={null}
{
  "name": "my-hono-app",
  "scripts": {
    "dev": "bun --hot run index.ts",
    "start": "bun run index.ts",
    "test": "bun test"
  },
  "dependencies": {
    "hono": "^4.0.0"
  },
  "devDependencies": {
    "bun-types": "latest"
  }
}
```

Run scripts:

```bash theme={null}
bun run dev   # Development with hot reload
bun run start # Production
bun test      # Run tests
```

## Deployment

### Standalone Binary

Build a standalone executable:

```bash theme={null}
bun build --compile --minify --sourcemap ./index.ts --outfile myapp
```

Run the binary:

```bash theme={null}
./myapp
```

### Docker

Create a `Dockerfile`:

```dockerfile Dockerfile theme={null}
FROM oven/bun:1

WORKDIR /app

COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile

COPY . .

EXPOSE 3000

CMD ["bun", "run", "index.ts"]
```

Build and run:

```bash theme={null}
docker build -t my-hono-app .
docker run -p 3000:3000 my-hono-app
```

### VPS/Cloud Deployment

<Steps>
  <Step title="Install Bun on your server">
    ```bash theme={null}
    curl -fsSL https://bun.sh/install | bash
    ```
  </Step>

  <Step title="Clone and install dependencies">
    ```bash theme={null}
    git clone https://github.com/your-username/my-app.git
    cd my-app
    bun install
    ```
  </Step>

  <Step title="Run with process manager">
    Use PM2 or systemd:

    ```bash theme={null}
    pm2 start "bun run index.ts" --name my-hono-app
    ```
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="Use hot reload in development">
    The `--hot` flag provides instant feedback during development.
  </Accordion>

  <Accordion title="Leverage Bun's built-in APIs">
    Use `Bun.file()`, `bun:sqlite`, and other built-in APIs for better performance.
  </Accordion>

  <Accordion title="Enable TypeScript">
    Bun runs TypeScript natively without a build step.
  </Accordion>

  <Accordion title="Use bun test">
    Bun's test runner is fast and includes built-in matchers.
  </Accordion>
</AccordionGroup>

## Performance Tips

* Bun is significantly faster than Node.js for I/O operations
* Use `Bun.file()` for file operations instead of `fs` module
* Leverage Bun's native WebSocket implementation
* Use `bun:sqlite` for embedded databases

## Resources

<CardGroup cols={2}>
  <Card title="Bun Documentation" icon="book" href="https://bun.sh/docs">
    Official Bun documentation
  </Card>

  <Card title="Bun Runtime APIs" icon="code" href="https://bun.sh/docs/api">
    Explore Bun's built-in APIs
  </Card>
</CardGroup>