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

# Vercel

> API reference for the Vercel adapter

The Vercel adapter provides utilities for running Hono applications on Vercel's Edge Runtime and Serverless Functions.

## Import

```ts theme={null}
import { handle, getConnInfo } from 'hono/vercel'
```

## Functions

### handle()

Converts a Hono application into a Vercel request handler.

```ts theme={null}
function handle(
  app: Hono
): (req: Request) => Response | Promise<Response>
```

#### Parameters

* `app` - The Hono application instance

#### Returns

A request handler function that can be exported as the default export.

#### Example

```ts theme={null}
import { Hono } from 'hono'
import { handle } from 'hono/vercel'

const app = new Hono()

app.get('/', (c) => {
  return c.text('Hello from Vercel!')
})

app.get('/api/users/:id', (c) => {
  const id = c.req.param('id')
  return c.json({ id, name: 'John Doe' })
})

app.post('/api/data', async (c) => {
  const body = await c.req.json()
  return c.json({ success: true, data: body })
})

export default handle(app)
```

### getConnInfo()

Extracts connection information from the Vercel request.

```ts theme={null}
function getConnInfo(c: Context): ConnInfo
```

#### Returns

```ts theme={null}
interface ConnInfo {
  remote: {
    address?: string  // Client IP from x-real-ip header
  }
}
```

#### Example

```ts theme={null}
import { Hono } from 'hono'
import { handle, getConnInfo } from 'hono/vercel'

const app = new Hono()

app.get('/', (c) => {
  const info = getConnInfo(c)
  return c.text(`Your IP: ${info.remote.address}`)
})

app.get('/api/location', (c) => {
  const info = getConnInfo(c)
  const country = c.req.header('x-vercel-ip-country')
  const city = c.req.header('x-vercel-ip-city')
  
  return c.json({
    ip: info.remote.address,
    country,
    city
  })
})

export default handle(app)
```

## Platform-Specific Notes

### Edge Runtime vs Serverless

Vercel supports two runtime environments:

* **Edge Runtime**: Runs on Vercel's Edge Network, closer to users for lower latency
* **Serverless Functions**: Traditional serverless functions with full Node.js compatibility

The adapter works with both. Configure the runtime in your `vercel.json`:

```json theme={null}
{
  "functions": {
    "api/**/*.ts": {
      "runtime": "edge"
    }
  }
}
```

### Request Headers

Vercel provides additional headers:

* `x-real-ip` - Client's real IP address
* `x-forwarded-for` - Proxy chain
* `x-vercel-ip-country` - Country code (e.g., "US")
* `x-vercel-ip-city` - City name (e.g., "San Francisco")
* `x-vercel-ip-country-region` - Region code (e.g., "CA")
* `x-vercel-ip-latitude` - Latitude
* `x-vercel-ip-longitude` - Longitude

### File Structure

For file-based routing in the `api/` directory:

```
project/
├── api/
│   ├── index.ts          # Handles /api
│   ├── hello.ts          # Handles /api/hello
│   └── users/
│       └── [id].ts       # Handles /api/users/:id
└── vercel.json
```

#### Example with Dynamic Routes

```ts theme={null}
// api/users/[id].ts
import { Hono } from 'hono'
import { handle } from 'hono/vercel'

const app = new Hono()

app.get('/api/users/:id', (c) => {
  const id = c.req.param('id')
  return c.json({ id, name: 'User ' + id })
})

export default handle(app)
```

### Catch-All Routes

For a single handler that handles all routes:

```ts theme={null}
// api/[...route].ts
import { Hono } from 'hono'
import { handle } from 'hono/vercel'

const app = new Hono()

app.get('/api/*', (c) => {
  return c.json({ path: c.req.path })
})

app.post('/api/data', async (c) => {
  const body = await c.req.json()
  return c.json(body)
})

export default handle(app)
```

### Environment Variables

Access Vercel environment variables directly:

```ts theme={null}
import { Hono } from 'hono'
import { handle } from 'hono/vercel'

const app = new Hono()

app.get('/api/config', (c) => {
  return c.json({
    nodeEnv: process.env.NODE_ENV,
    vercelEnv: process.env.VERCEL_ENV, // 'production', 'preview', or 'development'
    vercelUrl: process.env.VERCEL_URL,
  })
})

export default handle(app)
```

## Configuration

### vercel.json

```json theme={null}
{
  "functions": {
    "api/**/*.ts": {
      "runtime": "edge",
      "maxDuration": 10
    }
  },
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/api"
    }
  ]
}
```

### TypeScript Configuration

```json theme={null}
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "lib": ["ES2022"],
    "moduleResolution": "bundler",
    "types": ["@vercel/node"]
  }
}
```

## Deployment

### Using Vercel CLI

```bash theme={null}
# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

# Deploy to production
vercel --prod
```

### Using Git Integration

Connect your repository to Vercel:

1. Import your Git repository at [vercel.com/new](https://vercel.com/new)
2. Configure build settings (if needed)
3. Deploy automatically on every push

### Build Configuration

```json theme={null}
{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "installCommand": "npm install"
}
```

## Complete Example

```ts theme={null}
// api/index.ts
import { Hono } from 'hono'
import { handle, getConnInfo } from 'hono/vercel'
import { cors } from 'hono/cors'
import { logger } from 'hono/logger'

const app = new Hono()

app.use('*', cors())
app.use('*', logger())

app.get('/', (c) => {
  const info = getConnInfo(c)
  return c.json({ 
    message: 'Hello from Vercel!',
    ip: info.remote.address,
    country: c.req.header('x-vercel-ip-country')
  })
})

app.get('/api/hello/:name', (c) => {
  const name = c.req.param('name')
  return c.json({ message: `Hello, ${name}!` })
})

app.post('/api/echo', async (c) => {
  const body = await c.req.json()
  return c.json(body)
})

app.notFound((c) => {
  return c.json({ error: 'Not Found' }, 404)
})

app.onError((err, c) => {
  console.error(err)
  return c.json({ error: 'Internal Server Error' }, 500)
})

export default handle(app)
```

## See Also

* [Vercel Documentation](https://vercel.com/docs)
* [Edge Runtime](https://vercel.com/docs/functions/edge-functions)
* [Serverless Functions](https://vercel.com/docs/functions/serverless-functions)
* [Environment Variables](https://vercel.com/docs/projects/environment-variables)