{"id":18161,"library":"better-auth-vercel-geolocation","title":"better-auth-vercel-geolocation","description":"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.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/weepaho3/better-auth-vercel-geolocation","tags":["javascript","better-auth","better-auth-plugin","vercel","geolocation","session","nextjs","typescript"],"install":[{"cmd":"npm install better-auth-vercel-geolocation","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-vercel-geolocation","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-vercel-geolocation","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency required for plugin integration","package":"better-auth","optional":false}],"imports":[{"note":"ESM default. In CJS you must use require('better-auth-vercel-geolocation').geolocation.","wrong":"const geolocation = require('better-auth-vercel-geolocation').geolocation","symbol":"geolocation","correct":"import { geolocation } from 'better-auth-vercel-geolocation'"},{"note":"The client plugin is exported from a separate subpath 'better-auth-vercel-geolocation/client'.","wrong":"import { geolocationClient } from 'better-auth-vercel-geolocation'","symbol":"geolocationClient","correct":"import { geolocationClient } from 'better-auth-vercel-geolocation/client'"},{"note":"This is a TypeScript type. Use `import type` to avoid runtime inclusion.","wrong":"import { GeolocationPluginOptions } from 'better-auth-vercel-geolocation'","symbol":"GeolocationPluginOptions","correct":"import type { GeolocationPluginOptions } from 'better-auth-vercel-geolocation'"},{"note":"Type export for configuring which fields to store.","wrong":null,"symbol":"GeolocationFieldConfig","correct":"import type { GeolocationFieldConfig } from 'better-auth-vercel-geolocation'"}],"quickstart":{"code":"// Install: npm install better-auth-vercel-geolocation\n\n// auth.server.ts\nimport { betterAuth } from 'better-auth';\nimport { geolocation } from 'better-auth-vercel-geolocation';\n\nexport const auth = betterAuth({\n  plugins: [\n    geolocation({\n      fields: {\n        country: true,\n        city: true,\n        flag: true,\n        timezone: true,\n      },\n      updateOnRefresh: true,\n    }),\n  ],\n});\n\n// client.tsx\nimport { createAuthClient } from 'better-auth/react';\nimport { geolocationClient } from 'better-auth-vercel-geolocation/client';\n\nexport const authClient = createAuthClient({\n  plugins: [geolocationClient()],\n});\n\n// Usage in component:\nconst { data: session } = authClient.useSession();\nconsole.log(session?.city, session?.flag);","lang":"typescript","description":"Demonstrates server plugin setup with optional field config, client plugin initialization, and accessing geolocation fields from the session object in a React component."},"warnings":[{"fix":"Uninstall any old version and install better-auth-vercel-geolocation@1.0.0 or later.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Use Vercel preview deployments or local Vercel CLI (`vercel dev`) to test geolocation data.","message":"Geo fields will be `undefined` when running locally (non-Vercel environment) because Vercel request headers are not present.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure better-auth is updated: `npm install better-auth@^1.5.0`","message":"The peer dependency `better-auth` must be at version >=1.4.18 (latest v1.5.0). Using an older version will cause runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If you need reliable region/flag, compute them client-side from city/country.","message":"Fields `region` (Vercel Edge Network region) and `flag` are derived from other headers and may not be updated on every request.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Only import `geolocationClient` from `better-auth-vercel-geolocation/client` and pass it to the client.","message":"The client plugin `geolocationClient()` must be added to the client `createAuthClient()` call, not the server auth setup.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"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'`","cause":"Importing from wrong path; client subpath is not resolved correctly in some bundlers or TypeScript setups.","error":"Module not found: Can't resolve 'better-auth-vercel-geolocation/client'"},{"fix":"Check that plugin is added to both server and client. On localhost, fields will be undefined; use optional chaining: `session?.city`","cause":"Accessing geolocation fields on session without ensuring the plugin is properly configured or deployed on Vercel.","error":"TypeError: Cannot read properties of undefined (reading 'city')"},{"fix":"Run `npm install better-auth@^1.5.0` or update your package.json.","cause":"Incompatible peer dependency version.","error":"Error: better-auth version ^1.4.18 is required, but found 1.3.0"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}