Vercel Edge Function Action

Generate production-ready Vercel Edge Functions with geolocation, authentication, data transformation, proxy/caching patterns, TypeScript types, and comprehensive test suites.

When to Use This Command

Run this command when you need to create an Edge Function that runs at the CDN edge for low-latency, globally distributed processing.

• You need a geolocation-aware API that serves different content based on the visitor's country
• You want to implement JWT authentication at the edge before requests reach your origin
• You need a data transformation proxy that converts between JSON, XML, and CSV formats
• You want a caching proxy that reduces load on upstream APIs

Use it also when:

• You need Edge Functions with proper CORS headers, error handling, and cache controls
• You want auto-generated tests using mock NextRequest objects with geo data

Quick Start

Copy
# .claude/commands/vercel-edge-function-action.md
name: vercel-edge-function-action
description: Generate Vercel Edge Functions
arguments:
  name: Function name

Copy
# Generate a geo-content edge function
claude vercel-edge-function-action "geo-content"

Expected output:
Edge Function generated: geo-content
  api/edge/geo-content/
    index.ts        (main handler with GET/POST)
    types.ts        (TypeScript interfaces)
    utils.ts        (helper functions)
    config.ts       (edge configuration)
    __tests__/
      geo-content.test.ts (unit tests)

  Runtime: edge
  Methods: GET, POST
  Features: geolocation, caching, CORS

Core Concepts

Concept	Description
Edge Runtime	V8-based runtime running at CDN nodes worldwide
Geolocation	Access to request.geo with country, city, and region data
Cache Control	s-maxage and stale-while-revalidate headers for CDN caching
Edge Middleware	Logic that runs before requests reach serverless functions
CORS Helper	Utility for consistent cross-origin response headers

Edge Function Architecture:
  Client ──> Nearest Edge Node ──> Edge Function
                                       │
                    ┌──────────────────┼──────────────┐
                    v                  v              v
              Geo Lookup        Auth Check      Cache Check
                    │                  │              │
                    v                  v              v
              Localized         Validated        Cached or
              Response          Request          Fresh Data

Configuration

Parameter	Default	Description
name	required	Function name (used for directory and file naming)
type	generic	Template: geo, auth, transform, proxy, generic
methods	GET,POST	HTTP methods to implement
cache-time	300	Default s-maxage in seconds
cors-origins	["*"]	Allowed CORS origins

Best Practices

1. Keep edge functions lightweight -- The Edge Runtime has a 128KB code size limit. Avoid importing large libraries; use lightweight alternatives or implement logic inline.

2. Set appropriate cache headers -- Use s-maxage for CDN caching and stale-while-revalidate for background refresh. This dramatically reduces edge function invocations.

3. Handle missing geo data gracefully -- Not all requests include geolocation data. Always provide fallback values: const country = request.geo?.country || 'US'.

4. Use jose instead of jsonwebtoken at the edge -- The jsonwebtoken library is not compatible with the Edge Runtime. Use jose for JWT operations.

5. Test with mocked geo data -- Create mock NextRequest objects with custom geo properties to test geolocation logic without deploying to the edge.

Common Issues

1. Module not supported in Edge Runtime -- Node.js built-in modules (fs, path, crypto) are not available at the edge. Use Web APIs or edge-compatible alternatives.

2. Function exceeds size limit -- The Edge Runtime enforces strict code size limits. Tree-shake imports and remove unused dependencies to stay within bounds.

3. Geo data undefined in local development -- request.geo is only populated in production on Vercel. Use environment checks and mock data for local testing.