better-auth-firestore

better-auth-firestore

Note: If you're using @yultyyev/better-auth-firestore, please migrate to better-auth-firestore. The scoped package is deprecated. See Migration from Scoped Package below.

Firestore (Firebase Admin SDK) adapter for Better Auth. A drop-in replacement for the Auth.js Firebase adapter with matching data shape.

• Install: pnpm add better-auth-firestore firebase-admin better-auth
• Docs: Quickstart • Options • Migration • Emulator
• Example: See /examples/minimal for a complete Next.js App Router example
• AI skill: Cursor, Claude Code, Codex & 70+ agents — npx skills add yultyyev/better-auth-firestore • llms.txt

Related: Firebase Auth Plugin

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",
		},
	}),
});

Firebase Setup

1. Create a new Firebase project

• Go to Firebase Console
• Click "Add project" or "Create a project"
• Enter a project name and follow the setup wizard

2. Create Firestore Database

• In your Firebase project, go to Build → Firestore Database
• Click "Create database"
• Choose your preferred security rules mode (you can update rules later)
• 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. You can skip straight to the next step.

If you're upgrading from an earlier version that required a composite index on the verification collection (identifier ASC, createdAt DESC), you can safely leave that index in place or delete it — the adapter no longer depends on it.

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

• Go to Project Settings (gear icon) → Service Accounts
• Under "Firebase Admin SDK", click "Generate new private key"
• 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;
});

Default collection names:

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

Debug logging

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

Compatibility

Better Auth versions

Better Auth	Status	Notes
^1.5.0	✅ Recommended	Uses the latest API and security fixes.
^1.4.18	✅ Supported	Backward-compatible for existing projects.

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.

Runtime compatibility

Runtime	Supported	Notes
Node 18+	✅	Recommended
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.

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

If you're currently using @yultyyev/better-auth-firestore, migrate to better-auth-firestore:

• 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
  

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

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

FAQ

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.

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 using Firestore with Better Auth, 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.

Install works today from GitHub. The skills.sh listing page and README badge appear once indexed — tracking vercel-labs/skills#1601.

Related Links

• Better Auth Documentation
• Better Auth Adapter Guide
• llms.txt — Curated index for AI assistants and LLM crawlers
• better-auth-firebase-auth — Firebase Auth plugin (Phone OTP, Google, Email/Password)
• Auth.js Firebase Adapter (legacy, for reference)
• Auth.js joins Better Auth - Announcement

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.