better-auth-firestore: Instructions file for Codex

AI Assistant Guidelines

This document provides additional context for AI assistants working on this project. Please read README.md first for project overview and features.

Quick Reference

• Package name: better-auth-firestore
• Main Documentation: See README.md
• Contributing Guidelines: See CONTRIBUTING.md
• Adapter Guide: See Better Auth Adapter Guide

Current Project State

All phases are complete. The adapter is production-ready and actively maintained.

Phase 1: Core Adapter ✅ Complete
Phase 2: Collection naming strategies ✅ Complete
Phase 3: Composite index tooling ✅ Complete (generateIndexSetupUrl)
Phase 4: Emulator support ✅ Complete
Phase 5: Tests (Vitest + Firestore Emulator) ✅ Complete
Phase 6: CI/CD and Example Project ✅ Complete
Phase 7: Migration from scoped package ✅ Complete

Project Structure

src/
  firebase-adapter.ts    # Core Firestore adapter implementation
  firestore.ts           # initFirestore helper and Firestore utilities
  setup.ts               # generateIndexSetupUrl helper
  types.ts               # TypeScript types for adapter options
  index.ts               # Public exports
tests/
  *.test.ts              # Vitest integration tests (run against Firestore Emulator)
examples/
  minimal/               # Minimal Next.js App Router example
scripts/                 # Build/release scripts

Key Exports

import {
  firestoreAdapter,         // Main adapter factory
  initFirestore,            // Helper to initialize Firebase Admin + Firestore
  generateIndexSetupUrl,    // Generate Firebase Console URL for index creation
  backfillAccountIssuers,   // One-off data migration for Better Auth 1.7 (account.issuer)
} from "better-auth-firestore";

Adapter Options

firestoreAdapter({
  firestore?: Firestore;          // Firebase Admin Firestore instance (default: getFirestore())
  namingStrategy?: "default" | "snake_case";  // Collection naming convention
  collections?: {
    users?: string;
    sessions?: string;
    accounts?: string;
    verificationTokens?: string;
  };
  debugLogs?: boolean | DBAdapterDebugLogOption;
  migrationChecks?: boolean;      // default true: warn once at startup if account docs lack `issuer` (Better Auth 1.7)
});