better-auth-vercel-geolocation

1.2.0 verified Sat Apr 25 auth: no javascript

A better-auth plugin that enriches authentication sessions with Vercel edge geolocation data. Version 1.2.0 adds timezone support. Released as an MIT-licensed open source project with community-driven updates. Unlike manual IP geolocation, it reads Vercel's request headers (x-vercel-ip-*) server-side without external APIs or browser prompts. Requires Vercel deployment and better-auth >=1.4.18 (peer dependency ^1.5.0). Configurable fields include city, country, region, latitude, longitude, postal code, timezone, and a derived flag emoji. Ships TypeScript types and offers both server and client plugins.

Common errors

error Module not found: Can't resolve 'better-auth-vercel-geolocation/client' ↓

cause Importing from wrong path; client subpath is not resolved correctly in some bundlers or TypeScript setups.

fix

Ensure your package.json has "module": "ESNext" or configure TypeScript moduleResolution to bundler or node16. Or use full path: import { geolocationClient } from 'better-auth-vercel-geolocation/client'

error TypeError: Cannot read properties of undefined (reading 'city') ↓

cause Accessing geolocation fields on session without ensuring the plugin is properly configured or deployed on Vercel.

fix

Check that plugin is added to both server and client. On localhost, fields will be undefined; use optional chaining: session?.city

error Error: better-auth version ^1.4.18 is required, but found 1.3.0 ↓

cause Incompatible peer dependency version.

fix

Run npm install better-auth@^1.5.0 or update your package.json.

Warnings

breaking Version 1.0.0 changed the package name from previous beta naming; ensure you install 'better-auth-vercel-geolocation' and not an older package variant. ↓

fix Uninstall any old version and install better-auth-vercel-geolocation@1.0.0 or later.

gotcha Geo fields will be `undefined` when running locally (non-Vercel environment) because Vercel request headers are not present. ↓

fix Use Vercel preview deployments or local Vercel CLI (`vercel dev`) to test geolocation data.

gotcha The peer dependency `better-auth` must be at version >=1.4.18 (latest v1.5.0). Using an older version will cause runtime errors. ↓

fix Ensure better-auth is updated: `npm install better-auth@^1.5.0`

deprecated Fields `region` (Vercel Edge Network region) and `flag` are derived from other headers and may not be updated on every request. ↓

fix If you need reliable region/flag, compute them client-side from city/country.

gotcha The client plugin `geolocationClient()` must be added to the client `createAuthClient()` call, not the server auth setup. ↓

fix Only import `geolocationClient` from `better-auth-vercel-geolocation/client` and pass it to the client.

Install

npm install better-auth-vercel-geolocation

yarn add better-auth-vercel-geolocation

pnpm add better-auth-vercel-geolocation

Imports

geolocation

wrong

const geolocation = require('better-auth-vercel-geolocation').geolocation

correct

import { geolocation } from 'better-auth-vercel-geolocation'

ESM default. In CJS you must use require('better-auth-vercel-geolocation').geolocation.

geolocationClient

wrong

import { geolocationClient } from 'better-auth-vercel-geolocation'

correct

import { geolocationClient } from 'better-auth-vercel-geolocation/client'

The client plugin is exported from a separate subpath 'better-auth-vercel-geolocation/client'.

GeolocationPluginOptions

wrong

import { GeolocationPluginOptions } from 'better-auth-vercel-geolocation'

correct

import type { GeolocationPluginOptions } from 'better-auth-vercel-geolocation'

This is a TypeScript type. Use `import type` to avoid runtime inclusion.

GeolocationFieldConfig

import type { GeolocationFieldConfig } from 'better-auth-vercel-geolocation'

Type export for configuring which fields to store.

Quickstart

Demonstrates server plugin setup with optional field config, client plugin initialization, and accessing geolocation fields from the session object in a React component.

// Install: npm install better-auth-vercel-geolocation

// auth.server.ts
import { betterAuth } from 'better-auth';
import { geolocation } from 'better-auth-vercel-geolocation';

export const auth = betterAuth({
  plugins: [
    geolocation({
      fields: {
        country: true,
        city: true,
        flag: true,
        timezone: true,
      },
      updateOnRefresh: true,
    }),
  ],
});

// client.tsx
import { createAuthClient } from 'better-auth/react';
import { geolocationClient } from 'better-auth-vercel-geolocation/client';

export const authClient = createAuthClient({
  plugins: [geolocationClient()],
});

// Usage in component:
const { data: session } = authClient.useSession();
console.log(session?.city, session?.flag);