Firestore
Firebase's document database, queried directly from the client under security rules.
The rule
This is the whole text, exactly as your agent receives it. Nothing is held back for the paid tier.
Queries
- `limit()` on every query. An unbounded read on a growing collection costs money proportional to the collection.
- Paginate with cursors (
startAfter), not offsets. - Composite indexes belong in
firestore.indexes.json, committed. An index created by clicking a console link does not exist in the next environment. - No joins. Denormalise the fields a screen reads, and keep the write path that updates every copy.
Listeners
- Every
onSnapshotreturns an unsubscribe. Return it from the effect. - A leaked listener bills for as long as the tab is open.
Writes
setDocreplaces;updateDocmerges. Pick deliberately.serverTimestamp()for anything you order by — client clocks are unreliable.- Batches for related writes; transactions when you read then write atomically.
Modelling
- Shallow and wide beats deep and nested: a document is always read in full.
- Model around the screens that read the data, not around entities.
Never
- Never read a collection without a bound.
- Never rely on client-side filtering for access control — rules enforce it.
- Never store personal data in a document whose rules allow broad reads.
6 formats, one per tool
Each tab is the file that tool actually reads, at the path it actually looks in. Knowing where each one looks is most of the work of supporting it.
---
description: Firestore conventions
globs: ["src/services/firebase/**", "firestore.rules", "firestore.indexes.json"]
alwaysApply: false
---
# Firestore
## Queries
- **`limit()` on every query.** An unbounded read on a growing collection costs
money proportional to the collection.
- Paginate with cursors (`startAfter`), not offsets.
- Composite indexes belong in `firestore.indexes.json`, committed. An index
created by clicking a console link does not exist in the next environment.
- No joins. Denormalise the fields a screen reads, and keep the write path that
updates every copy.
## Listeners
- Every `onSnapshot` returns an unsubscribe. Return it from the effect.
- A leaked listener bills for as long as the tab is open.
## Writes
- `setDoc` replaces; `updateDoc` merges. Pick deliberately.
- `serverTimestamp()` for anything you order by — client clocks are unreliable.
- Batches for related writes; transactions when you read then write atomically.
## Modelling
- Shallow and wide beats deep and nested: a document is always read in full.
- Model around the screens that read the data, not around entities.
## Never
- Never read a collection without a bound.
- Never rely on client-side filtering for access control — rules enforce it.
- Never store personal data in a document whose rules allow broad reads.
Hand-written by the module author, frontmatter and all. It is the source the four derived formats are rendered from, so a correction lands here first.
What else this module writes
The rule is one file of several. Selecting Firestore contributes all of this too — merged with every other module you pick, with conflicts resolved rather than duplicated.
Advisory history
Every time this rule turned out to be wrong, and what we did about it.
This rule has been accurate since it was published. That is a fact about the rule, not a promise about the future — which is the whole reason this section exists.
Pro tells you the day a correction lands that affects a repo you actually have.
See what Pro adds →Rules people add alongside this one
The wizard picks the rest of the stack with you, writes all 6 formats, and leaves a manifest so check can tell you when any of it drifts.