Registry / auth-security / better-auth-vercel-geolocation

better-auth-vercel-geolocation

library1.2.0jsnpmunverified

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.

auth-security aws

npm install better-auth-vercel-geolocation

github ↗package ↗

INSTALL

IMPORT

SIG · BETTER-AUTH-VERCEL

better-auth-vercel-geolocation

auth-securityjavascriptv1.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

geolocation

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

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

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

geolocationClient

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

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

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

GeolocationPluginOptions

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

✗ import { 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.

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);

Debug

Known issues

breakingVersion 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.

affects: <1.0.0

gotchaGeo 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.

affects: >=0.0.0

gotchaThe 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`

affects: >=1.0.0

deprecatedFields `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.

affects: >=1.0.0

gotchaThe 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.

affects: >=0.0.0

Errors

Common errors & fixes

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

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'`

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

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: better-auth version ^1.4.18 is required, but found 1.3.0

Incompatible peer dependency version.

fix

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

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

better-authrequiredpeer dependency required for plugin integration

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/weepaho3/better-auth-vercel-geolocation ↗

packagehttps://www.npmjs.com/package/better-auth-vercel-geolocation ↗