better-auth-vercel-geolocation
v1.2.1
Published
A better-auth plugin that enriches sessions with Vercel edge geolocation data.
Downloads
809
Maintainers
Readme
better-auth-vercel-geolocation
A better-auth plugin that enriches the auth session with Vercel edge geolocation data. On session create and refresh, it reads the [x-vercel-ip-* headers](https://vercel.com/docs/headers/request-headers) server-side and writes the configured fields into the session record — no browser permission prompt, no extra API call.
[!NOTE] Requires deployment on Vercel. In local development, geo fields will be
undefined.
Features
- Zero-config defaults — stores city, country, countryRegion and flag out of the box
- Configurable fields — pick exactly which geo fields you need
- Auto-refresh — Updates geo data when the session refreshes
Installation
npm install better-auth-vercel-geolocationRequires better-auth >= 1.5.0 as a peer dependency.
Quick start
1. Add the plugin to your auth config
import { betterAuth } from 'better-auth';
import { geolocation } from 'better-auth-vercel-geolocation';
export const auth = betterAuth({
plugins: [geolocation()],
});2. Migrate the database
npx auth@latest migrateIf you use an ORM adapter such as Drizzle or Prisma, run npx auth@latest generate instead and apply the generated schema with your ORM's migration tooling.
3. Add the client plugin
import { createAuthClient } from 'better-auth/react';
import { geolocationClient } from 'better-auth-vercel-geolocation/client';
export const authClient = createAuthClient({
plugins: [geolocationClient()],
});The session now includes geolocation fields. data holds { session, user } and is null when nobody is signed in:
const { data } = authClient.useSession();
data?.session.city; // "Hamburg"
data?.session.country; // "DE"
data?.session.countryRegion; // "HH"
data?.session.flag; // "🇩🇪"Types
The fields are inferred on auth.$Infer.Session.session, on the result of auth.api.getSession() and on the session of the client:
type GeoSession = typeof auth.$Infer.Session.session;
const result = await auth.api.getSession({ headers });
result?.session.city; // string | null | undefined
const { data } = authClient.useSession();
data?.session.city; // string | null | undefinedOptions
| Option | Type | Default | Description |
| ----------------- | ------------------------ | ---------------------------------------- | --------------------------------------------- |
| fields | GeolocationFieldConfig | { city, country, countryRegion, flag } | Which fields to store on the session |
| updateOnRefresh | boolean | true | Update geo data when the session is refreshed |
Available fields
The values come from Vercel's x-vercel-ip-* request headers. Off Vercel they are empty, and a client can send those headers itself, so they must not be used for security decisions.
| Field | Header | Example | Default |
| --------------- | ------------------------------ | ----------------- | ------- |
| city | x-vercel-ip-city | "Hamburg" | ✅ |
| country | x-vercel-ip-country | "DE" | ✅ |
| countryRegion | x-vercel-ip-country-region | "HH" | ✅ |
| flag | (derived from country) | "🇩🇪" | ✅ |
| latitude | x-vercel-ip-latitude | "53.5573" | |
| longitude | x-vercel-ip-longitude | "9.9652" | |
| postalCode | x-vercel-ip-postal-code | "20359" | |
| region | (Vercel Edge Network region) | "fra1" | |
| timezone | x-vercel-ip-timezone | "Europe/Berlin" | |
License
MIT
