Registry / database / better-auth-firestore

better-auth-firestore

JSON →
library1.2.2jsnpmunverified

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-firestore
INSTALL
IMPORT
SIG · BETTER-AUTH-FIREST
B
better-auth-firestore
databasejavascriptv1.2.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

firestoreAdapter
import { firestoreAdapter } from 'better-auth-firestore';
const firestoreAdapter = require('better-auth-firestore');
This package is ESM-only, requiring Node.js 22+. CommonJS `require()` is not supported.
initFirestore
import { initFirestore } from 'better-auth-firestore';
import initFirestore from 'better-auth-firestore';
A named export for convenient Firebase Admin SDK initialization, not a default export.
generateIndexSetupUrl
import { generateIndexSetupUrl } from 'better-auth-firestore';
Utility function to generate a Firebase Console URL for creating required Firestore indexes.

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.

import { betterAuth } from "better-auth"; import { firestoreAdapter, initFirestore } from "better-auth-firestore"; import { cert } from "firebase-admin/app"; import { getFirestore } from "firebase-admin/firestore"; // Also useful for direct Firestore access // Initialize Firebase Admin SDK for Firestore. // Ensure these environment variables are securely managed in production. 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" // Optional: name for the Firebase App instance }); // Configure Better Auth with the Firestore adapter. export const auth = betterAuth({ // Additional Better Auth configuration options would go here, // e.g., providers, callbacks, etc. secret: process.env.AUTH_SECRET ?? 'super-secret-key-for-development-only', // Required for Better Auth database: firestoreAdapter({ firestore, // Optional: Customize collection names if needed. // These are the default values if not specified: collections: { users: "users", sessions: "sessions", accounts: "accounts", verificationTokens: "verificationTokens" }, // Optional: Define a naming strategy for fields (e.g., 'default' or 'snake_case') namingStrategy: "default" }) }); // Example of how to access the initialized auth instance (e.g., in an API route) async function getUserSession(sessionId: string) { // In a real application, you would use `auth.getSession()` or similar // This is just to demonstrate the `auth` object is available. // const session = await auth.getSession({ req: someRequest }); // console.log("Session:", session); console.log(`Auth instance initialized with Firestore adapter and sessionId: ${sessionId}`); // You can also directly interact with Firestore via the 'firestore' object const userDoc = await firestore.collection('users').doc('someUserId').get(); if (userDoc.exists) { console.log("Example user data:", userDoc.data()); } } // Call the example function (for demonstration purposes, not part of actual quickstart) getUserSession('example-session-id-123');
Debug
Known issues
breakingThe package moved from `@yultyyev/better-auth-firestore` to an unscoped name `better-auth-firestore`. Users of the scoped package must migrate to the new name.
fix
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`.
affects: <1.1.1
gotchaFirestore `IN` queries have a hard limit of 30 values. Prior to `v1.2.0`, queries exceeding this limit would fail. The adapter now chunks these queries automatically.
fix
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.
affects: <1.2.0
gotchaThis package is ESM-only and requires Node.js 22+ as specified in its `engines` field. Older Node.js versions or CommonJS environments are not supported.
fix
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.
affects: *
gotchaNode.js ESM compatibility requires explicit `.js` extensions for relative imports. Versions prior to `v1.1.4` might encounter module resolution errors in certain ESM configurations.
fix
Upgrade to `better-auth-firestore@1.1.4` or later to ensure proper `.js` extension handling for ESM compatibility.
affects: <1.1.4
gotchaA composite Firestore index on the `verification` collection is required for proper functionality. Without it, operations involving verification tokens will fail.
fix
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).
affects: *
gotchaCompatibility with `better-auth` versions is important. `better-auth-firestore@1.1.3` introduced explicit support for `better-auth@1.5`, and future `better-auth` major versions may require corresponding `better-auth-firestore` updates.
fix
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.
affects: <1.1.3
Errors
Common errors & fixes
ReferenceError: require is not defined
Attempting to use CommonJS `require()` in an ES Modules (ESM) environment where only `import` statements are supported.
fix
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.
ERR_MODULE_NOT_FOUND: Cannot find module './some-module' resolved with .js extension
Node.js ESM resolution failed to find a relative module, often due to missing `.js` extensions in import paths in older versions of the library.
fix
Upgrade `better-auth-firestore` to `v1.1.4` or later, which includes fixes for ESM compatibility by adding `.js` extensions to relative imports.
FirebaseError: The query uses an 'in' or 'array-contains-any' clause with more than 30 values. Make sure your 'in' or 'array-contains-any' queries do not exceed this limit.
A Firestore query generated by the adapter exceeded the 30-value limit for `IN` clauses.
fix
Upgrade `better-auth-firestore` to `v1.2.0` or later. This version introduces automatic chunking of `IN` queries to work around this limitation.
FirebaseError: A required index is missing or out of date. You can create it with the following link: [link to Firebase Console]
The necessary composite index for the `verificationTokens` collection (on `token` and `expires`) has not been created in your Firestore database.
fix
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).
Upgrade
Version history
1.2.2latest on npm
Audit
Dependencies
better-authrequiredCore dependency; provides the Better Auth framework this adapter integrates with.
firebase-adminrequiredRequired for interacting with Firestore via the Firebase Admin SDK.
typescriptrequiredPackage ships with types and is primarily used in TypeScript projects.
Agent activity
50 hits · last 30 days
node
40
OpenAI (training)
1
Resources
better-auth-firestore — npm install better-auth-firestore · libregistry