Firebase Firestore

Firebase Firestore Skill

Production-ready Firestore queries with TypeScript, a proper type lifecycle, structured error handling, and the tuple return pattern. This file holds the rules; detailed code lives in the references.

Workflow

1. Define types with the lifecycle pattern (Base → Firestore → Application → DTOs).
2. Write a transform that converts a Firestore document to the application type (Timestamp → Date).
3. Implement queries returning the tuple [ServiceError | null, Data | null].
4. Handle errors via ServiceError + categorizeServiceError(), logging structured context at every error point.
5. Cover edge cases — empty input, not found, permission denied.

Place queries in features/[feature]/server/db/[resource]-queries.ts; types in features/[feature]/types/[resource].ts.

Type Lifecycle

Firestore needs different representations at different stages (full utilities in types.md):

type ResourceBase = { name: string; status: "active" | "inactive" };  // 1. business fields only
type ResourceFirestore = WithFirestoreTimestamps<ResourceBase>;       // 2. with Timestamp objects
type Resource = WithDates<ResourceBase>;                              // 3. app type: id + Date objects
type CreateResourceDto = CreateDto<ResourceBase>;                     // 4. create DTO
type UpdateResourceDto = UpdateDto<ResourceBase>;                     // 5. update DTO

Error Handling

Contract: the ServiceError class and categorizeServiceError() here implement the universal ServiceError contract defined in the error-handling skill. Consumers branch on boolean properties (isNotFound, isRetryable, isPermissionDenied) without knowing the backend is Firestore.

• Every query returns a tuple — [ServiceError, null] on failure, [null, data] on success. Validate input first, wrap the Firestore call in try/catch, run the caught error through categorizeServiceError(error, resourceName). Worked code in errors.md and examples.md.
• Consumers branch on the error flags:
  • Server Action — isNotFound → specific message; otherwise return error.message (or a generic).
  • Page loader — isNotFound → notFound(); isRetryable → throw (let error.tsx handle); otherwise throw a generic error.

Transform Functions

Convert a Firestore document to the application type — spread the data, add id, and turn Timestamps into Dates:

function transformToResource(docId: string, data: FirebaseFirestore.DocumentData): Resource {
  return { id: docId, ...data, createdAt: data.createdAt?.toDate(), updatedAt: data.updatedAt?.toDate() } as Resource;
}

Related Skills

• error-handling — defines the ServiceError contract this skill implements.
• server-actions — server actions that consume these queries.
• db-migration — migrating Firestore data.