Vercel Geo Plugin

Enrich your analytics events with geographic data from Vercel's edge network.

Overview

When your Next.js app runs on Vercel, every request includes geographic headers. The Vercel Geo plugin extracts this data and adds it to your analytics events automatically.

No external API calls. No additional latency. Just free geo data from Vercel's edge.

What Data You Get

Vercel provides the following headers on every request:

Header	Property	Example
`x-vercel-ip-country`	`country`	`US`
`x-vercel-ip-country-region`	`region`	`CA`
`x-vercel-ip-city`	`city`	`San Francisco`
`x-vercel-ip-latitude`	`latitude`	`37.7749`
`x-vercel-ip-longitude`	`longitude`	`-122.4194`
`x-vercel-ip-timezone`	`timezone`	`America/Los_Angeles`

Installation

npm install @nextlytics/core

Configuration

// src/nextlytics.ts
import { Nextlytics } from "@nextlytics/core/server";
import { vercelGeoPlugin } from "@nextlytics/core/plugins/vercel-geo";
import { postgrestBackend } from "@nextlytics/core/backends/postgrest";
 
export const { middleware, analytics } = Nextlytics({
  plugins: [vercelGeoPlugin()],
  backends: [
    postgrestBackend({
      url: process.env.SUPABASE_URL! + "/rest/v1",
      apiKey: process.env.SUPABASE_SERVICE_ROLE_KEY!,
    }),
  ],
});

Options

Option	Type	Default	Description
`geoPropertyName`	`string`	`"geo"`	Property name to store geo data under

Custom Property Name

vercelGeoPlugin({
  geoPropertyName: "location", // Events will have `location.country`, etc.
});

Event Output

Every analytics event will include a geo object (or your custom property name):

{
  "type": "pageView",
  "properties": {
    "geo": {
      "country": "US",
      "region": "CA",
      "city": "San Francisco",
      "latitude": 37.7749,
      "longitude": -122.4194,
      "timezone": "America/Los_Angeles"
    }
  }
}

Use Cases

Geographic Analytics

See where your users are coming from. Filter by country, region, or city in your analytics backend.

Personalization

Nextlytics stores geo data on analytics events. For real-time personalization during rendering, read the Vercel geo headers directly:

// In a server component
import { headers } from "next/headers";
 
const country = (await headers()).get("x-vercel-ip-country");
 
if (country === "DE") {
  // Show German pricing
}

Compliance

Know which users are in GDPR regions (EU countries) or CCPA regions (California).

Requirements

Vercel deployment: This plugin only works when deployed to Vercel
Edge/Serverless functions: Headers are available in middleware and API routes
No local development data: Geo headers are not present in next dev

Local Development

During local development (next dev), Vercel geo headers are not present. The plugin gracefully handles this by simply not adding geo data to events.

To test geo functionality locally, you can mock the headers:

// middleware.ts (development only)
import type { NextRequest } from "next/server";
import { NextResponse } from "next/server";
 
export function middleware(request: NextRequest) {
  if (process.env.NODE_ENV === "development") {
    const requestHeaders = new Headers(request.headers);
    requestHeaders.set("x-vercel-ip-country", "US");
    requestHeaders.set("x-vercel-ip-city", "San Francisco");
 
    return NextResponse.next({
      request: {
        headers: requestHeaders,
      },
    });
  }
 
  return NextResponse.next();
}

Privacy Considerations

Geo data is derived from IP addresses at Vercel's edge. The actual IP address is not stored by Nextlytics unless you explicitly configure it.

City-level location data may be considered personal data under GDPR. Consult your legal team if you're unsure about compliance requirements.

Vercel Geo