The `better-auth-firestore` package provides a robust Firestore adapter for the `Better Auth` authentication library, utilizing the Firebase Admin SDK. Currently at stable version `1.2.2`, it receives frequent updates, with several patch and minor releases in the past few months addressing bugs and adding features. This library acts as a drop-in replacement for `Auth.js` (formerly `NextAuth.js`) Firebase adapter, maintaining a compatible data shape, which simplifies migrations. Its key differentiators include built-in handling for Firestore-specific limitations, such as chunking `IN` queries that exceed the 30-value cap, and providing helper functions like `initFirestore` for easy setup and `generateIndexSetupUrl` for required index creation. It strictly targets Node.js 22+ and is designed for TypeScript projects, shipping with full type definitions. While it handles Firestore data storage, `better-auth-firebase-auth` is recommended for actual Firebase Authentication provider integration.
npm install better-auth-firestoreVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize the Firestore adapter with `better-auth` using Firebase Admin SDK credentials, enabling session and user data persistence in Firestore.
Update your package dependencies and imports from `@yultyyev/better-auth-firestore` to `better-auth-firestore`. Run `npm uninstall @yultyyev/better-auth-firestore && npm install better-auth-firestore`.
Upgrade to `better-auth-firestore@1.2.0` or later to automatically handle `IN` query chunking. If unable to upgrade, ensure your queries against the adapter do not exceed 30 values in a single `IN` clause.
Ensure your project runs on Node.js version 22 or higher and is configured for ES Modules. If migrating from CommonJS, update your `package.json` with `"type": "module"` and adjust import/export statements.
Upgrade to `better-auth-firestore@1.1.4` or later to ensure proper `.js` extension handling for ESM compatibility.
Use the `generateIndexSetupUrl` helper from `better-auth-firestore` to get a direct link to create the index in the Firebase Console, or create it manually: Collection ID `verificationTokens`, Fields: `token` (Ascending), `expires` (Ascending).
Always keep `better-auth-firestore` and `better-auth` updated to their latest compatible versions. If experiencing unexpected behavior, check the release notes for both packages for specific compatibility requirements.
Refactor your code to use ES Modules `import` syntax for `better-auth-firestore` and ensure your `package.json` specifies `"type": "module"` if running in Node.js ESM.
Upgrade `better-auth-firestore` to `v1.1.4` or later, which includes fixes for ESM compatibility by adding `.js` extensions to relative imports.
Upgrade `better-auth-firestore` to `v1.2.0` or later. This version introduces automatic chunking of `IN` queries to work around this limitation.
Follow the provided link in the error message, or use `generateIndexSetupUrl` from the package to create the required index through the Firebase Console. Alternatively, create it manually via `verificationTokens` collection, `token` (Ascending), `expires` (Ascending).