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

# Vercel Edge Runtime SDK

> Error monitoring and performance tracking for Vercel Edge Functions

The Sentry Vercel Edge Runtime SDK provides error monitoring and performance tracking for Edge Functions and Edge Middleware running on Vercel's Edge Network.

<Note>
  The `@sentry/vercel-edge` package is a low-level building block. For Next.js applications on Vercel, use `@sentry/nextjs` which includes Edge Runtime support automatically.
</Note>

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @sentry/vercel-edge
  ```

  ```bash yarn theme={null}
  yarn add @sentry/vercel-edge
  ```

  ```bash pnpm theme={null}
  pnpm add @sentry/vercel-edge
  ```
</CodeGroup>

## When to Use

Use `@sentry/vercel-edge` for:

* Standalone Edge Functions on Vercel
* Edge Middleware (if not using Next.js)
* Custom Edge applications

**For Next.js applications**, use `@sentry/nextjs` instead, which includes full Edge Runtime support.

## Basic Setup

### Edge Function

```typescript theme={null}
// api/hello.ts
import * as Sentry from '@sentry/vercel-edge';

Sentry.init({
  dsn: 'YOUR_DSN_HERE',
  tracesSampleRate: 1.0,
  environment: process.env.VERCEL_ENV,
});

export const config = {
  runtime: 'edge',
};

export default async function handler(request: Request) {
  try {
    return new Response(
      JSON.stringify({ message: 'Hello from Edge!' }),
      {
        status: 200,
        headers: { 'Content-Type': 'application/json' },
      },
    );
  } catch (error) {
    Sentry.captureException(error);
    return new Response(
      JSON.stringify({ error: 'Internal Server Error' }),
      { status: 500 },
    );
  }
}
```

### Edge Middleware

```typescript theme={null}
// middleware.ts
import * as Sentry from '@sentry/vercel-edge';
import { NextRequest, NextResponse } from 'next/server';

Sentry.init({
  dsn: 'YOUR_DSN_HERE',
  tracesSampleRate: 1.0,
});

export function middleware(request: NextRequest) {
  try {
    // Your middleware logic
    const response = NextResponse.next();
    
    // Add custom headers
    response.headers.set('x-custom-header', 'value');
    
    return response;
  } catch (error) {
    Sentry.captureException(error);
    return NextResponse.next();
  }
}

export const config = {
  matcher: '/api/:path*',
};
```

## Error Handling

### Manual Error Capture

```typescript theme={null}
import * as Sentry from '@sentry/vercel-edge';

export const config = { runtime: 'edge' };

export default async function handler(request: Request) {
  const url = new URL(request.url);
  const userId = url.searchParams.get('userId');
  
  try {
    const user = await fetchUser(userId);
    return new Response(JSON.stringify(user));
  } catch (error) {
    Sentry.captureException(error, {
      tags: {
        function: 'fetchUser',
        userId: userId || 'unknown',
      },
      contexts: {
        request: {
          url: request.url,
          method: request.method,
        },
      },
    });
    
    return new Response(
      JSON.stringify({ error: 'User not found' }),
      { status: 404 },
    );
  }
}
```

### Validation Errors

```typescript theme={null}
import * as Sentry from '@sentry/vercel-edge';

export const config = { runtime: 'edge' };

export default async function handler(request: Request) {
  if (request.method !== 'POST') {
    return new Response('Method not allowed', { status: 405 });
  }
  
  try {
    const body = await request.json();
    
    if (!body.email) {
      const error = new Error('Email is required');
      Sentry.captureException(error, {
        level: 'warning',
        tags: { validation: 'email' },
      });
      
      return new Response(
        JSON.stringify({ error: 'Email is required' }),
        { status: 400 },
      );
    }
    
    // Process valid request
    return new Response(JSON.stringify({ success: true }));
  } catch (error) {
    Sentry.captureException(error);
    return new Response('Internal Server Error', { status: 500 });
  }
}
```

## Performance Monitoring

### Custom Spans

```typescript theme={null}
import * as Sentry from '@sentry/vercel-edge';

export const config = { runtime: 'edge' };

export default async function handler(request: Request) {
  return await Sentry.startSpan(
    {
      name: 'edge-function-handler',
      op: 'function.edge',
    },
    async () => {
      const data = await fetchData();
      return new Response(JSON.stringify(data));
    },
  );
}
```

### External API Calls

```typescript theme={null}
import * as Sentry from '@sentry/vercel-edge';

export const config = { runtime: 'edge' };

async function fetchExternalData(id: string) {
  return await Sentry.startSpan(
    {
      name: 'external-api-call',
      op: 'http.client',
      attributes: {
        'http.method': 'GET',
        'http.url': `https://api.example.com/data/${id}`,
      },
    },
    async () => {
      const response = await fetch(`https://api.example.com/data/${id}`);
      return response.json();
    },
  );
}

export default async function handler(request: Request) {
  const url = new URL(request.url);
  const id = url.searchParams.get('id');
  
  const data = await fetchExternalData(id!);
  return new Response(JSON.stringify(data));
}
```

### Database Queries

```typescript theme={null}
import * as Sentry from '@sentry/vercel-edge';
import { createClient } from '@vercel/edge-config';

const edgeConfig = createClient(process.env.EDGE_CONFIG);

export const config = { runtime: 'edge' };

export default async function handler(request: Request) {
  const value = await Sentry.startSpan(
    {
      name: 'edge-config.get',
      op: 'db.query',
      attributes: {
        'db.system': 'edge-config',
      },
    },
    async () => {
      return await edgeConfig.get('feature-flag');
    },
  );
  
  return new Response(JSON.stringify({ value }));
}
```

## Context and User Information

### Request Context

```typescript theme={null}
import * as Sentry from '@sentry/vercel-edge';

export const config = { runtime: 'edge' };

export default async function handler(request: Request) {
  const url = new URL(request.url);
  
  Sentry.setContext('request', {
    url: request.url,
    method: request.method,
    headers: Object.fromEntries(request.headers),
  });
  
  Sentry.setContext('geo', {
    city: request.headers.get('x-vercel-ip-city'),
    country: request.headers.get('x-vercel-ip-country'),
    region: request.headers.get('x-vercel-ip-country-region'),
  });
  
  // Your handler logic
  return new Response('OK');
}
```

### User Identification

```typescript theme={null}
import * as Sentry from '@sentry/vercel-edge';

export const config = { runtime: 'edge' };

export default async function handler(request: Request) {
  // Extract user from JWT or cookie
  const token = request.headers.get('authorization')?.replace('Bearer ', '');
  
  if (token) {
    const user = await verifyToken(token);
    
    Sentry.setUser({
      id: user.id,
      email: user.email,
      username: user.username,
    });
  }
  
  // Your handler logic
  return new Response('OK');
}
```

## Edge Runtime Limitations

<Warning>
  The Edge Runtime has limitations:

  * No Node.js APIs (fs, path, etc.)
  * Smaller bundle size limits
  * Limited execution time
  * No native modules

  Sentry automatically adjusts for these constraints.
</Warning>

## Environment Variables

Configure via Vercel dashboard or `.env`:

```bash theme={null}
# Required
SENTRY_DSN=your-dsn-here

# Optional
SENTRY_TRACES_SAMPLE_RATE=1.0
SENTRY_ENVIRONMENT=production
SENTRY_RELEASE=1.0.0
```

Access Vercel system environment variables:

```typescript theme={null}
import * as Sentry from '@sentry/vercel-edge';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.VERCEL_ENV, // 'production', 'preview', or 'development'
  release: process.env.VERCEL_GIT_COMMIT_SHA,
});
```

## Vercel Integration

### Preview Deployments

```typescript theme={null}
import * as Sentry from '@sentry/vercel-edge';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.VERCEL_ENV,
  
  // Only sample in production
  tracesSampleRate: process.env.VERCEL_ENV === 'production' ? 0.1 : 1.0,
  
  beforeSend(event) {
    // Add deployment URL to events
    if (process.env.VERCEL_URL) {
      event.tags = event.tags || {};
      event.tags.deployment_url = process.env.VERCEL_URL;
    }
    return event;
  },
});
```

### Edge Config

Use Vercel Edge Config for feature flags:

```typescript theme={null}
import * as Sentry from '@sentry/vercel-edge';
import { createClient } from '@vercel/edge-config';

const edgeConfig = createClient(process.env.EDGE_CONFIG);

export const config = { runtime: 'edge' };

export default async function handler(request: Request) {
  const sentryEnabled = await edgeConfig.get('sentry-enabled');
  
  if (!sentryEnabled) {
    // Skip Sentry initialization
    return new Response('OK');
  }
  
  // Your handler with Sentry
}
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Next.js SDK" icon="triangle-exclamation">
    For Next.js apps, use @sentry/nextjs instead of this package.
  </Card>

  <Card title="Minimize Bundle" icon="compress">
    Keep edge function bundles small for fast cold starts.
  </Card>

  <Card title="Set Context" icon="tag">
    Add geo and request data for better debugging.
  </Card>

  <Card title="Sample Wisely" icon="filter">
    Use lower sample rates in production to control volume.
  </Card>
</CardGroup>

## Troubleshooting

<Accordion title="Bundle Size Errors">
  Edge functions have strict size limits:

  1. Minimize dependencies
  2. Use dynamic imports where possible
  3. Check bundle analyzer output
</Accordion>

<Accordion title="Timeout Issues">
  Edge functions have execution time limits:

  1. Optimize async operations
  2. Use appropriate timeouts for external calls
  3. Consider moving heavy operations to serverless functions
</Accordion>

## Next Steps

<CardGroup cols={2}>
  <Card title="Next.js" icon="next" href="/nextjs">
    Use Next.js SDK for full framework support
  </Card>

  <Card title="Edge Middleware" icon="filter" href="/edge-middleware">
    Advanced middleware patterns
  </Card>

  <Card title="Edge Config" icon="database" href="/edge-config">
    Use Vercel Edge Config
  </Card>

  <Card title="Vercel" icon="v" href="/vercel">
    Vercel deployment best practices
  </Card>
</CardGroup>