> ## 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.

# Cloudflare Workers

> Deploy Hono applications to Cloudflare Workers

Cloudflare Workers is an edge computing platform that runs JavaScript at Cloudflare's global network. Hono works perfectly with Cloudflare Workers with zero configuration.

## Quick Start

Create a new Hono project for Cloudflare Workers:

<CodeGroup>
  ```bash npm theme={null}
  npm create hono@latest my-app
  ```

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

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

  ```bash bun theme={null}
  bun create hono my-app
  ```
</CodeGroup>

Select "cloudflare-workers" as your template when prompted.

## Installation

If you're adding Hono to an existing Cloudflare Workers project:

```bash theme={null}
npm install hono
```

## Basic Usage

Create your application in `src/index.ts`:

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

const app = new Hono()

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

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

export default app
```

<Note>
  Cloudflare Workers expects your application to be exported as `default`. Hono's `app` object is a valid fetch handler.
</Note>

## Adapter Features

The Cloudflare Workers adapter provides several utilities:

### Static Files

Serve static files using the `serveStatic` middleware:

```typescript theme={null}
import { Hono } from 'hono'
import { serveStatic } from 'hono/cloudflare-workers'

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

Upgrade HTTP connections to WebSocket:

```typescript theme={null}
import { Hono } from 'hono'
import { upgradeWebSocket } from 'hono/cloudflare-workers'

const app = new Hono()

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 default app
```

### Connection Info

Get connection information including IP address:

```typescript theme={null}
import { Hono } from 'hono'
import { getConnInfo } from 'hono/cloudflare-workers'

const app = new Hono()

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

export default app
```

## Configuration

### wrangler.toml

Configure your Worker with `wrangler.toml`:

```toml wrangler.toml theme={null}
name = "my-hono-app"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[build]
command = "npm install && npm run build"

# Add environment variables
[vars]
ENVIRONMENT = "production"

# Configure KV namespace
[[kv_namespaces]]
binding = "MY_KV"
id = "your-kv-id"

# Configure R2 bucket
[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-bucket"
```

## Accessing Bindings

Access Cloudflare bindings through the context:

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

type Bindings = {
  MY_KV: KVNamespace
  MY_BUCKET: R2Bucket
  DB: D1Database
}

const app = new Hono<{ Bindings: Bindings }>()

app.get('/kv/:key', async (c) => {
  const key = c.req.param('key')
  const value = await c.env.MY_KV.get(key)
  return c.text(value || 'Not found')
})

app.get('/r2/:key', async (c) => {
  const key = c.req.param('key')
  const object = await c.env.MY_BUCKET.get(key)
  if (!object) return c.notFound()
  return c.body(await object.arrayBuffer())
})

export default app
```

## Deployment

<Steps>
  <Step title="Install Wrangler">
    Install the Cloudflare Workers CLI:

    ```bash theme={null}
    npm install -g wrangler
    ```
  </Step>

  <Step title="Login to Cloudflare">
    Authenticate with your Cloudflare account:

    ```bash theme={null}
    wrangler login
    ```
  </Step>

  <Step title="Deploy">
    Deploy your application:

    ```bash theme={null}
    wrangler deploy
    ```

    Your app will be available at `https://my-hono-app.<your-subdomain>.workers.dev`
  </Step>
</Steps>

## Development

Run your Worker locally:

```bash theme={null}
wrangler dev
```

This starts a local development server with hot reload at `http://localhost:8787`.

## Environment Variables

Add secrets for sensitive data:

```bash theme={null}
wrangler secret put API_KEY
```

Access secrets in your code:

```typescript theme={null}
type Bindings = {
  API_KEY: string
}

const app = new Hono<{ Bindings: Bindings }>()

app.get('/api', (c) => {
  const apiKey = c.env.API_KEY
  // Use the API key
})
```

## Best Practices

<AccordionGroup>
  <Accordion title="Keep bundle size small">
    Workers have a size limit. Use tree-shaking and avoid large dependencies.
  </Accordion>

  <Accordion title="Use TypeScript">
    TypeScript provides excellent type safety for bindings and context.
  </Accordion>

  <Accordion title="Handle errors gracefully">
    Always implement error handling as Workers run at the edge.
  </Accordion>

  <Accordion title="Leverage caching">
    Use Cache API and KV for better performance.
  </Accordion>
</AccordionGroup>

## Resources

<CardGroup cols={2}>
  <Card title="Cloudflare Workers Docs" icon="book" href="https://developers.cloudflare.com/workers/">
    Official Cloudflare Workers documentation
  </Card>

  <Card title="Wrangler CLI" icon="terminal" href="https://developers.cloudflare.com/workers/wrangler/">
    Learn more about the Wrangler CLI
  </Card>
</CardGroup>