Skip to content

Repository files navigation

better-auth-firestore

npm version CI License: MIT skills.sh

Use Firestore as the database for Better Auth. better-auth-firestore is a Better Auth database adapter that stores users, sessions, accounts and verification tokens in your Firebase project's Firestore through the Firebase Admin SDK, so a Firebase app can add Better Auth without running a second database such as Postgres, MySQL or MongoDB.

"Use Firestore as the database for my Better Auth app."

With the agent skill installed, Claude Code, Cursor or Codex follows it: installs the packages, sets up Firebase Admin credentials (including the FIREBASE_PRIVATE_KEY newline fix), adds firestoreAdapter to betterAuth(), and keeps the auth routes off the Edge runtime.


Use with Firebase Authentication

For Firebase Authentication integration with Better Auth, see better-auth-firebase-auth. It provides:

  • Firebase Phone Authentication (SMS OTP) — no Twilio required
  • Google Sign-In via Firebase OAuth flow
  • Email/Password sign-in and password reset via Firebase
  • Full TypeScript support with separate server/client entry points

Use better-auth-firebase-auth for authentication and better-auth-firestore for data storage. They are designed to be used together:

import { firestoreAdapter } from "better-auth-firestore";
import { firebaseAuthPlugin } from "better-auth-firebase-auth/server";

export const auth = betterAuth({
  database: firestoreAdapter({ firestore }),
  plugins: [firebaseAuthPlugin({ firebaseAdminAuth: getAuth() })],
});

Installation

npm

npm install better-auth-firestore firebase-admin better-auth

pnpm

pnpm add better-auth-firestore firebase-admin better-auth

yarn

yarn add better-auth-firestore firebase-admin better-auth

bun

bun add better-auth-firestore firebase-admin better-auth

Minimal usage

import { firestoreAdapter } from "better-auth-firestore";
import { betterAuth } from "better-auth";
import { getFirestore } from "firebase-admin/firestore";

export const auth = betterAuth({
  database: firestoreAdapter({ firestore: getFirestore() })
});

Quick start

import { betterAuth } from "better-auth";
import { firestoreAdapter, initFirestore } from "better-auth-firestore";
import { cert } from "firebase-admin/app";

const firestore = initFirestore({
	credential: cert({
		projectId: process.env.FIREBASE_PROJECT_ID!,
		clientEmail: process.env.FIREBASE_CLIENT_EMAIL!,
		privateKey: process.env.FIREBASE_PRIVATE_KEY!.replace(/\\n/g, "\n"),
	}),
	projectId: process.env.FIREBASE_PROJECT_ID!,
	name: "better-auth",
});

export const auth = betterAuth({
	// ... your Better Auth options
	database: firestoreAdapter({
		firestore,
		namingStrategy: "default", // or "snake_case"
		collections: {
			// users: "users",
			// sessions: "sessions",
			// accounts: "accounts",
			// verificationTokens: "verificationTokens",
		},
	}),
});

Set it up with your AI agent

Install the agent skill once, and Claude Code, Cursor, Codex, Copilot, Windsurf and 70+ other agents can set the adapter up from a plain request:

npx skills add yultyyev/better-auth-firestore

Then paste one of these prompts:

Use Firestore as the database for my Better Auth app.
Add Better Auth to my Firebase app without Postgres.
Move my Auth.js / NextAuth Firebase adapter setup to Better Auth with Firestore.
Set up the Firestore emulator for Better Auth local development and tests.
Fix the FIREBASE_PRIVATE_KEY error in my Better Auth Firestore setup.

Firebase Setup

1. Create a new Firebase project

  1. Go to Firebase Console
  2. Click "Add project" or "Create a project"
  3. Enter a project name and follow the setup wizard

2. Create Firestore Database

  1. In your Firebase project, go to Build → Firestore Database
  2. Click "Create database"
  3. Choose your preferred security rules mode (you can update rules later)
  4. Select a location for your database

3. Firestore Index (Optional)

No composite index is required. As of v1.1, the adapter sorts filtered queries — including verification-token lookups — in memory, so Firestore's automatic single-field indexes are sufficient. As of v1.3 that includes rateLimit.storage: "database": the adapter implements Better Auth's incrementOne natively and evaluates the limiter's range guards in memory inside a Firestore transaction, so only an equality filter on key ever reaches Firestore.

If you're upgrading from an earlier version that required composite indexes — on the verification collection (identifier ASC, createdAt DESC, before v1.1) or on rateLimit (key/lastRequest and key/count/lastRequest, before v1.3) — you can safely leave them in place or delete them; the adapter no longer depends on either.

The generateIndexSetupUrl / getIndexConfig helpers and the bundled firestore.indexes.json are still exported for advanced setups (for example, if you run your own where + orderBy queries directly against the verification collection outside the adapter). They default to the verificationTokens collection; pass "verification_tokens" when using the snake_case naming strategy, or your custom collection name.

4. Generate Service Account Key

  1. Go to Project Settings (gear icon) → Service Accounts
  2. Under "Firebase Admin SDK", click "Generate new private key"
  3. Download the JSON file (keep it secure - never commit it to version control)

5. Extract Environment Variables

From the downloaded service account JSON file, extract these values:

  • project_id → FIREBASE_PROJECT_ID
  • client_email → FIREBASE_CLIENT_EMAIL
  • private_key → FIREBASE_PRIVATE_KEY (requires newline replacement - see Troubleshooting)

Alternative: You can use the JSON file directly by setting GOOGLE_APPLICATION_CREDENTIALS environment variable to the path of your service account JSON file.

6. (Optional) Set up Security Rules

The adapter uses the Firebase Admin SDK (server-side), so Firestore security rules should deny direct client access. See Firestore Security Rules below.

Environment Variables

Required environment variables:

  • FIREBASE_PROJECT_ID - Your Firebase project ID
  • FIREBASE_CLIENT_EMAIL - Service account email from the JSON file
  • FIREBASE_PRIVATE_KEY - Service account private key (with newlines properly escaped)

Note: The FIREBASE_PRIVATE_KEY often contains literal \n characters in environment variables. See Troubleshooting for how to handle this.

Options

firestoreAdapter({
	firestore?: Firestore;
	namingStrategy?: "default" | "snake_case";
	collections?: { users?: string; sessions?: string; accounts?: string; verificationTokens?: string };
	debugLogs?: boolean | DBAdapterDebugLogOption;
	migrationChecks?: boolean; // default true — see "Upgrading to Better Auth 1.7"
});

Default collection names:

  • users: "users"
  • sessions: "sessions"
  • accounts: "accounts"
  • verificationTokens: "verification_tokens" (snake_case) or "verificationTokens" (default)

Custom model names: a Better Auth modelName (for example user: { modelName: "app_users" }, or a plugin model) names the Firestore collection directly and takes precedence over collections. The mapping is applied consistently, including for operations Better Auth runs inside adapter.transaction (such as sign-up).

Debug logging

firestoreAdapter({
  firestore,
  debugLogs: true, // Enable verbose logging
});

Compatibility

Better Auth versions

Better Auth Status Notes
^1.7.0 ✅ Recommended Requires adapter v1.3+ (native incrementOne). Use 1.7.3 or later; deployments on 1.7.0–1.7.2 must run the account issuer backfill first.
^1.6.0 ✅ Supported Tested in CI alongside 1.7; the same adapter release works with both.
< 1.6 ⚠️ Not covered by CI Pin an older adapter release (≤ v1.2) if you need one.

For older projects: if your app still uses older Better Auth patterns (createAuth + adapter), this adapter remains compatible, but new projects should use betterAuth + database.

TypeScript versions

TypeScript Status Notes
7.x ✅ Supported Native compiler. Produces byte-identical declarations to 5.x/6.x.
6.x ✅ Supported Drop-in — no config changes required.
5.x ✅ Supported Minimum supported version is 5.0; used for the published build.

Every version above is exercised in CI (typecheck + build). TypeScript is an optional peer dependency, so JavaScript-only projects never install it.

Runtime compatibility

Runtime Supported Notes
Node 22+ ✅ Required (active LTS and newer). import works throughout; require() needs 22.12+ — see below.
Next.js on Vercel (Node.js runtime) ✅ Default serverless runtime — fully supported
Cloud Functions / Cloud Run ✅ Provide FIREBASE_* creds
Vercel Edge Runtime (runtime = 'edge') ❌ Firebase Admin SDK requires Node.js
Cloudflare Workers ❌ Firebase Admin SDK requires Node.js

Vercel works. The ❌ above applies only if you explicitly set export const runtime = 'edge' on a route. The default Node.js serverless runtime on Vercel is fully supported.

ESM and CommonJS. The package ships a single ESM build. import works on any supported Node. require("better-auth-firestore") relies on Node's require(esm), unflagged since 22.12 — so CommonJS callers (Firebase Cloud Functions and friends) need 22.12 or newer, which every current 22.x LTS release satisfies. TypeScript projects that emit CommonJS need "module": "nodenext" — the older "node16" setting predates require(esm) and reports TS1479.

Collections & Data Shape

The adapter maintains the same data shape as Auth.js/NextAuth for seamless migration:

Collection Typical fields
users id, email, name, image, createdAt, updatedAt
accounts provider, providerAccountId, userId, access_token, refresh_token
sessions sessionToken, userId, expires
verificationTokens identifier, token, expires

Defaults: Collections default to users, sessions, accounts, verification_tokens (snake_case) / verificationTokens (default). See Options to customize collection names.

Note: No composite index is required. Verification-token lookups are sorted in memory. See Firebase Setup - Step 3 for details.

Minimal Firestore Security Rules (server/admin only)

Since this adapter uses the Firebase Admin SDK (server-side), Firestore security rules should deny direct client access:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if false;
    }
  }
}

Why this vs Auth.js Firebase adapter?

Feature Better Auth Firestore Auth.js Firebase Adapter
Status ✅ Active development Now maintained by Better Auth team (announcement)
Firebase Admin SDK ✅ Uses Admin SDK ✅ Uses Admin SDK
Data shape compatibility ✅ Matching shape, migration-free -
Drop-in replacement ✅ Yes -

This adapter is the Better Auth-native solution for Firestore users, recommended for new projects.

Migration from Scoped Package

The scoped package @yultyyev/better-auth-firestore was unpublished from npm in August 2026 (it had been deprecated since January). Projects that still reference it keep working from their installed node_modules, but any fresh install — a new machine, CI, rm -rf node_modules — fails with 404 Not Found. The fix is a rename; the API is identical:

  1. Update package name in your dependencies:

    npm uninstall @yultyyev/better-auth-firestore
    npm install better-auth-firestore
    # or
    pnpm remove @yultyyev/better-auth-firestore
    pnpm add better-auth-firestore
  2. Update import statements:

    // Before
    import { firestoreAdapter } from "@yultyyev/better-auth-firestore";
    
    // After
    import { firestoreAdapter } from "better-auth-firestore";

That's it! The API is identical, so no code changes are needed beyond the import path.

Upgrading to Better Auth 1.7

Starting a new app? Use Better Auth 1.7.3 or later. Nothing in this section applies to you.

Better Auth 1.7 changed how accounts are identified and what it requires from database adapters. Two things matter for Firestore users — read the official 1.7 upgrade guide for everything else (OAuth provider, SSO, SCIM, MCP, …).

1. Adapter v1.3+ is required. 1.7 made incrementOne a mandatory adapter method and removed the fallback earlier versions relied on. With adapter ≤ v1.2 on Better Auth 1.7, sign-in still works but every feature built on atomic counters throws Adapter "firestore" must implement incrementOne — database-backed rate limiting, organization invitations and team seats, device authorization, and two-factor lockout. v1.3 implements it natively and also works with 1.6, so upgrade the adapter first, independently of Better Auth. Better Auth 1.7.22 and later need adapter v1.3.4+. They look records up by "field is null", which earlier adapters never match for a field that was simply not set: the OAuth provider asks for consent again on every authorization, and refresh-token rotation fails. Consuming a verification value (password reset, magic links, authorization codes) also deletes older ones with an id != filter that earlier adapters sent to Firestore as a field query needing a composite index.

2. On 1.7.0–1.7.2 only, existing account documents need an issuer. Better Auth 1.7.3 went back to identifying accounts by (providerId, accountId), as 1.6 did, so on 1.7.3 or later there is nothing to migrate: upgrade straight to the latest 1.7 and skip this step. If you already backfilled, nothing needs undoing. The official guide's cleanup for 1.7.0–1.7.2 databases relaxes a SQL NOT NULL column and unique index that Firestore never had, and 1.7.3+ ignores the extra field.

1.7.0–1.7.2 identify an account by the pair (issuer, accountId) and store issuer on every new account. Documents written by earlier versions don't have it, so after upgrading, those releases can't find them — existing users can no longer sign in until the field is backfilled. SQL users get this from npx auth migrate; Firestore has no migration runner, so the adapter ships the migration as one command. Run it with the same credentials your app uses (GOOGLE_APPLICATION_CREDENTIALS, the FIREBASE_* variables from Environment Variables, or --service-account key.json):

npx better-auth-firestore backfill-account-issuers            # dry run: prints the report, writes nothing
npx better-auth-firestore backfill-account-issuers --apply    # writes, with authentication writes paused

Add --collection / --naming-strategy snake_case if you customised the adapter, and --issuer <providerId>=<url> for a provider whose real issuer the backfill can't determine on its own — the built-in cognito, paybin, and microsoft (Entra ID) providers, and the fixed-id generic-OAuth helpers okta, auth0, keycloak, and microsoft-entra-id, whose issuer depends on how they're configured or on the live token. Those are reported as unresolved (exit status 1) until you supply one, rather than stamped with a value that may be wrong. google, apple, facebook, and line publish a fixed real issuer and resolve automatically; every other built-in social provider gets the synthetic local:oauth:<providerId> form 1.7 assigns when a provider has none of its own. (slack is ambiguous — the built-in social provider has no issuer, the generic-OAuth helper uses https://slack.com; it defaults to the synthetic form, so pass --issuer slack=https://slack.com if you use the helper.) --help lists everything.

Already ran this on adapter v1.3.0? That release stamped local:oauth:google instead of the real https://accounts.google.com (and likewise for apple, facebook, and line), so those users still can't sign in even though the field is set — and because the field is set, the startup warning stays silent and a re-run of the old command reported nothing to do. Upgrade the adapter and run the backfill again: it detects that exact wrong value, repairs it, and lists the affected documents as wrong issuers left by the v1.3.0 backfill. Deliberate issuers you supplied yourself are never touched. Users who signed in while the issuer was wrong already self-healed — Better Auth linked a fresh, correctly stamped account to their email — which leaves the v1.3.0 row behind as a stale twin. Those are reported separately as superseded and deliberately left alone, because re-stamping them would create a duplicate (issuer, accountId); they're inert on 1.7.0–1.7.2 (which never look the old issuer up), but on 1.7.3+ they share their twin's (providerId, accountId), so delete them when you move to 1.7.3 or later.

The command mirrors 1.7's own rules: credential → local:credential (and repairs accountId to equal userId), siwe → local:siwe, google/apple/facebook/line → their real issuer, and every other provider without one of its own → local:oauth:<encodeURIComponent(providerId)>. It refuses to guess for providers with a real issuer it can't determine offline — those come back unresolved until you pass --issuer. It is idempotent (stamped documents are skipped, apart from the v1.3.0 values noted above, which are repaired), paginates, and exits with status 1 when it finds (issuer, accountId) collisions or documents it cannot resolve — 1.7 treats that pair as unique, so resolve those by hand before deploying. The same logic is available programmatically as backfillAccountIssuers({ firestore, dryRun, issuers, resolveIssuer, … }).

If you forget: the adapter checks on startup and logs a [better-auth-firestore] warning with the exact command whenever Better Auth expects issuer but account documents lack it (two aggregation reads per process; migrationChecks: false disables it).

Run the backfill (dry run, then real) before your first deploy on Better Auth 1.7.0–1.7.2; it ships in v1.3 and is harmless on 1.6 and 1.7.3+. Once you're on v1.3 you can also delete the rateLimit composite indexes; see Firestore Index.

Plugin authors: 1.7 removed internalAdapter.findOAuthUser(email, accountId, providerId). Use findAccountOwnerByKey, which takes { providerId, accountId } on 1.7.3+ and { issuer, accountId } on 1.7.0–1.7.2 (where linkAccount / createOAuthUser also need issuer). If you use better-auth-firebase-auth, upgrade it to v2.2.2 or later — earlier releases fail every sign-in on 1.7 (v2.2.0 and v2.2.1 handle only 1.7.0–1.7.2). One build supports Better Auth 1.5–1.7, and it ships npx better-auth-firebase-auth backfill-account-issuers for 1.7.0–1.7.2. Its providerId: "firebase" account documents are already covered by the backfill above: the default rule stamps them local:oauth:firebase, exactly the issuer that plugin uses.

Migration from Auth.js/NextAuth

For complete migration steps, see the Better Auth NextAuth Migration Guide, which covers route handlers, client setup, and server-side session handling.

Adapter-Specific Migration

This adapter uses the same default collection names and field names as Auth.js Firebase adapter, making it a drop-in replacement for the database adapter portion of your migration:

  • Collection names: users, sessions, accounts, verificationTokens (same as Auth.js)
  • Field names: sessionToken, userId, providerAccountId, etc. (same as Auth.js)
  • Data shape: Identical, so no data migration scripts needed

Simply replace your Auth.js Firebase adapter with this one:

// Before (Auth.js)
import { FirestoreAdapter } from "@auth/firebase-adapter";

// After (Better Auth)
import { firestoreAdapter } from "better-auth-firestore";

// Same Firestore instance, same collections, same data shape
export const auth = betterAuth({
  database: firestoreAdapter({ firestore }),
});

If you were using custom collection names with Auth.js, you can override them:

firestoreAdapter({
	firestore,
	collections: {
		accounts: "authjs_accounts", // or whatever custom names you were using
		// ... other overrides
	},
});

Recipes

Use snake_case collections

firestoreAdapter({
  firestore,
  namingStrategy: "snake_case",
});

Keep Auth.js collection names (no data migration)

firestoreAdapter({
  firestore,
  collections: {
    accounts: "accounts", // or your custom collection names
    // ... other overrides
  },
});

Usage with Next.js (App Router)

// app/api/auth/[...all]/route.ts
import { toNextJsHandler } from "better-auth/next-js";
import { auth } from "@/lib/auth";

export const { GET, POST } = toNextJsHandler(auth);

Usage in Node.js script

import { firestoreAdapter } from "better-auth-firestore";
import { betterAuth } from "better-auth";
import { initializeApp, cert } from "firebase-admin/app";
import { getFirestore } from "firebase-admin/firestore";

const app = initializeApp({
  credential: cert({
    projectId: process.env.FIREBASE_PROJECT_ID,
    clientEmail: process.env.FIREBASE_CLIENT_EMAIL,
    privateKey: process.env.FIREBASE_PRIVATE_KEY?.replace(/\\n/g, "\n"),
  }),
});

export const auth = betterAuth({
  database: firestoreAdapter({ firestore: getFirestore(app) }),
});

Using the Firestore Emulator

The adapter fully supports the Firestore Emulator for both local development and testing. When FIRESTORE_EMULATOR_HOST is set, the Firebase Admin SDK automatically routes all requests to the emulator instead of production Firestore. Collection names remain unchanged — the adapter uses the same collections in emulator mode as in production.

Local development

# 1. Start the emulator
docker run -d --rm \
	--name auth-firestore \
	-p 8080:8080 \
	google/cloud-sdk:emulators gcloud beta emulators firestore start \
	--host-port=0.0.0.0:8080

# 2. Set the env var and start your app
export FIRESTORE_EMULATOR_HOST=localhost:8080
pnpm run dev

Or add FIRESTORE_EMULATOR_HOST=localhost:8080 to your .env file (supported by Next.js, Vite, etc.).

Note: No credential or service account setup is needed when using the emulator — the Admin SDK skips authentication automatically.

Running tests

export FIRESTORE_EMULATOR_HOST=localhost:8080
pnpm vitest run

Troubleshooting

Error: FIREBASE_PRIVATE_KEY has literal \n

Symptom: Authentication fails or you see errors about invalid private key format.

Fix: Environment variables often store newlines as literal \n strings. Replace them at runtime:

privateKey: process.env.FIREBASE_PRIVATE_KEY!.replace(/\\n/g, "\n")

See also the AI Assistant Skill — agents use it to avoid this mistake during setup.

Error: Requests hang on local dev

Symptom: Firebase Admin SDK requests hang or time out during local development.

Fix: Use the Firestore Emulator and set FIRESTORE_EMULATOR_HOST=localhost:8080 before running your app. See Using the Firestore Emulator for setup instructions. The AI Assistant Skill includes emulator commands for agents.

Error: 9 FAILED_PRECONDITION: The query requires an index

Symptom: Queries on verification tokens fail with a FAILED_PRECONDITION / "The query requires an index" error (often surfaced by Better Auth as Failed to parse state).

Fix: Upgrade to better-auth-firestore v1.1 or later. Older versions issued a where + orderBy query that required a composite index; the adapter now sorts filtered queries in memory, so no index is needed. After upgrading, the error disappears and any previously created composite index can be removed.

If you cannot upgrade immediately, create the index from the URL in the error message, or generate it with:

import { generateIndexSetupUrl } from "better-auth-firestore";
const url = generateIndexSetupUrl(process.env.FIREBASE_PROJECT_ID!);
console.log(url); // Open this URL to create the index

Error: updateMany is not a function, every sign-in returns 429, or 9 FAILED_PRECONDITION on rateLimit

Symptom: With rateLimit.storage: "database", auth routes return 500 with TypeError: updateMany is not a function, every request is rate limited even when the counter never rises, or production fails with 9 FAILED_PRECONDITION: The query requires an index on the rateLimit collection.

Fix: Upgrade to v1.3 or later. The adapter implements Better Auth's incrementOne natively: the limiter's guards are evaluated in memory inside a Firestore transaction, so no composite index is needed anymore. (v1.2.x routed the limiter through a transactional updateMany fallback that pushed two inequality filters to Firestore and therefore required the rateLimit composite indexes.)

Note that Firestore emulators do not enforce composite indexes, so index failures only reproduce against a real Firestore instance.

Error: Adapter "firestore" must implement incrementOne for atomic guarded counter updates

Symptom: After upgrading to Better Auth 1.7, rate-limited routes, organization invitations / team seats, device authorization, or two-factor verification throw this error.

Fix: Upgrade better-auth-firestore to v1.3 or later. Better Auth 1.7 made incrementOne a required adapter method and removed the fallback older adapter versions relied on. See Upgrading to Better Auth 1.7.

Existing users can't sign in after upgrading to Better Auth 1.7

Symptom: Sign-up works, but accounts created before the upgrade fail to sign in (email/password reports invalid credentials; social sign-in reports the account as not linked, or links a duplicate account to the email-matched user).

Fix: Upgrade Better Auth to 1.7.3 or later, which looks accounts up by (providerId, accountId) again. To stay on 1.7.0–1.7.2, run npx better-auth-firestore backfill-account-issuers --apply once to stamp the issuer field those releases use to look accounts up (dry run first without --apply). The adapter logs the same command at startup while documents are missing it. See Upgrading to Better Auth 1.7.

If only your social users are affected and the backfill says there's nothing to do, you ran it on adapter v1.3.0, which stamped local:oauth:google rather than the real https://accounts.google.com (same for apple, facebook, line). The field is present but wrong, so neither the startup warning nor the old command flags it. Upgrade the adapter and re-run the backfill — it repairs those documents. See Upgrading to Better Auth 1.7.

FAQ

Can I use Better Auth with Firebase?

Yes. Better Auth needs a database for its users, sessions, accounts and verification tokens, and better-auth-firestore makes your Firebase project's Firestore that database. To sign users in through Firebase Authentication (phone OTP, Google, email/password), add better-auth-firebase-auth on top: the two are built to work together. See Use with Firebase Authentication and the Quick start.

Do I need Postgres or another SQL database to use Better Auth with Firestore?

No. Every Better Auth model, including plugin models such as rateLimit, is stored as a Firestore collection, so Firestore is the only database. The adapter needs a server-side Node.js runtime for the Firebase Admin SDK; see Which runtimes are supported?.

Can I migrate from Auth.js / NextAuth without changing existing Firestore data?

Yes. better-auth-firestore is designed as a drop-in replacement for the Auth.js Firebase adapter with matching collection names and field shapes by default, so most projects do not need a Firestore data migration. See Migration from Auth.js/NextAuth for the adapter-specific details. The AI Assistant Skill includes a migration guide for Cursor, Claude Code, and other agents.

What's the difference between better-auth-firestore and better-auth-firebase-auth?

better-auth-firestore is a database adapter for storing Better Auth users, sessions, accounts, and verification tokens in Firestore through the Firebase Admin SDK. better-auth-firebase-auth is for Firebase Authentication provider integration such as Email/Password, Google sign-in, client/server token generation, and password reset flows. Use the Firestore adapter for data storage and the Firebase Auth plugin when you need Firebase Authentication features. Both packages have AI Assistant Skills on skills.sh.

Which runtimes are supported?

This package supports any server-side Node.js runtime: Next.js on Vercel (the default serverless runtime), Cloud Functions, Cloud Run, and standalone Node.js. The only restriction is the Edge Runtime — if you explicitly set export const runtime = 'edge' on a route, the Firebase Admin SDK will not load. Standard Vercel deployments are fully supported. See Runtime compatibility for the full matrix. Agents should follow the runtime table in the AI Assistant Skill.

Do I need a Firestore composite index for verification tokens?

No. Better Auth's verification-token lookup filters by identifier and orders by createdAt, which historically required a composite index. As of v1.1 the adapter applies the filter server-side and sorts the (small, per-identifier) result set in memory, so no composite index is required. See Firestore Index (Optional) for the optional tooling that remains available.

Does the adapter support Better Auth 1.7?

Yes, from v1.3. The same release also works with Better Auth 1.6 (both are tested in CI). 1.7.3 and later need no data migration; if you deploy 1.7.0–1.7.2 with existing users, run the account issuer backfill first — see Upgrading to Better Auth 1.7.

AI Assistant Skill

The agent skill lives at skills/firestore-better-auth/SKILL.md. It works with Cursor, Claude Code, Codex, Copilot, Windsurf, and 70+ other agents via the skills.sh ecosystem.

The skill teaches AI assistants the correct setup, environment variable handling, and common gotchas. It also triggers when you ask about adding Better Auth to a Firebase app, using Firestore with Better Auth, pairing it with Firebase Authentication, migrating from Auth.js/NextAuth, or troubleshooting FIREBASE_PRIVATE_KEY issues.

npx skills add yultyyev/better-auth-firestore

For LLM crawlers and AI search, see also llms.txt at the repo root — a curated index of documentation, the skill file, and key setup facts.

Skill page: skills.sh/yultyyev/better-auth-firestore/firestore-better-auth.


Related Links

Build

pnpm build

Reporting issues

Found a bug? First make sure you're on the latest version, then open an issue with the package version and a minimal repro. Please redact secrets and PII (Firebase project IDs, FIREBASE_PRIVATE_KEY, tokens, and create_composite index URLs).

Contributing

Contributions are welcome. See CONTRIBUTING.md for development setup and code style.

License

MIT.