Skip to main content
skill CX Codex

firebase-cloud-firestore — Claude Code skill: what it does

The firebase-cloud-firestore skill guides an agent through setting up Cloud Firestore in a Flutter app: schema design, queries, real-time listeners and security rules.

MIT ★ 674 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add evanca/flutter-ai-rules
/plugin install flutter-ai-skills@flutter-ai-rules
Open on GitHub

What firebase-cloud-firestore does

The skill covers building Cloud Firestore features in Flutter apps: structuring documents and collections, running reads, writes, batches and transactions, wiring up real-time listeners, and paginating results with cursors instead of offsets. It also lays out indexing guidance — which fields to exempt from indexing to stay under the 500-writes-per-second limit on sequential fields, and how to spread writes across document paths to dodge hotspots at scale.

It ships Dart snippets for common tasks: creating a document with an auto-generated ID, running a 500-operation batch, a transaction that increments a counter, and a snapshots() subscription handling DocumentChangeType events. There's also guidance on picking Cloud Firestore over Realtime Database based on query complexity and latency needs.

The skill targets Flutter projects built on the cloud_firestore package; offline caching is on by default on mobile, with cache size configurable through Settings.CACHE_SIZE_UNLIMITED.

What it helps with

  • structure Firestore collections and subcollections for a Flutter app
  • paginate query results with cursors instead of offsets
  • set up index exemptions for timestamp fields to avoid write limits
  • build an atomic batch or transaction for multi-document updates
  • subscribe to real-time document changes with a listener

Example prompts for the agent

  • Set up Cloud Firestore in this Flutter project
  • Write a transaction that increments a visit counter
  • Paginate the cities collection using cursors instead of offset

How to install firebase-cloud-firestore

1Plugin marketplace

/plugin marketplace add evanca/flutter-ai-rules
/plugin install flutter-ai-skills@flutter-ai-rules

This installs the whole flutter-ai-skills plugin with all its skills

2Skills CLI (Vercel)

npx skills add evanca/flutter-ai-rules --skill firebase-cloud-firestore -a claude-code

3Manually: put the files in place

~/.claude/skills/firebase-cloud-firestore/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/firebase-cloud-firestore/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about firebase-cloud-firestore

How do I install firebase-cloud-firestore in Claude Code?

Run /plugin marketplace add evanca/flutter-ai-rules, then /plugin install flutter-ai-skills@flutter-ai-rules.

What does the firebase-cloud-firestore skill do?

It covers building Cloud Firestore functionality in Flutter apps: data modeling, CRUD, batches, transactions, listeners, indexing and security rules.

When should this skill point you to Firestore over Realtime Database?

Firestore fits hierarchical data, compound queries and transactions, while Realtime Database suits simple lookups with very low sync latency.

Source text

SKILL.md · MIT
---
name: firebase-cloud-firestore
description: "Use when setting up Firestore, designing schemas, doing CRUD, creating listeners, paginating queries, configuring indexes, enabling offline persistence, or writing security rules."
license: MIT
---

# Firebase Cloud Firestore Skill

This skill defines how to correctly implement Cloud Firestore in Flutter applications, covering data modeling, queries, real-time updates, security rules, and scale optimization.

## When to Use

Use this skill when:

* Setting up and configuring Cloud Firestore in a Flutter project.
* Designing document and collection structure or planning subcollections.
* Performing read, write, batch, or transaction operations.
* Implementing real-time listeners or paginated queries.
* Optimizing for scale and avoiding write hotspots.
* Writing or debugging Firestore security rules.

---

## 1. Database Selection

Choose **Cloud Firestore** when the app needs:
- Rich, hierarchical data models with subcollections.
- Complex queries: chaining filters, combining filtering and sorting on a property.
- Transactions that atomically read and write data from any part of the database.
- High availability (typical uptime 99.999%) or critical-level reliability.
- Automatic scaling to millions of concurrent users.

Use **Realtime Database** instead for simple data models requiring simple lookups and extremely low-latency synchronization (typical response times under 10ms).

---

## 2. Setup and Configuration

```
flutter pub add cloud_firestore
```

```dart
import 'package:cloud_firestore/cloud_firestore.dart';

final db = FirebaseFirestore.instance; // after Firebase.initializeApp()
```

**Location:**
- Select the database location closest to users and compute resources.
- Use **multi-region** locations for critical apps (maximum availability and durability).
- Use **regional** locations for lower costs and lower write latency.

**iOS/macOS:** Consider pre-compiled frameworks to improve build times:
```ruby
pod 'FirebaseFirestore',
  :git => 'https://github.com/invertase/firestore-ios-sdk-frameworks.git',
  :tag => 'IOS_SDK_VERSION'
```

**Offline persistence** is enabled by default on mobile. Configure cache size:
```dart
FirebaseFirestore.instance.settings = const Settings(
  persistenceEnabled: true,
  cacheSizeBytes: Settings.CACHE_SIZE_UNLIMITED,
);
```

---

## 3. Document Structure

- Avoid document IDs `.` and `..` (special meaning in Firestore paths).
- Avoid forward slashes (`/`) in document IDs (path separators).
- **Do not** use monotonically increasing document IDs (e.g., `Customer1`, `Customer2`) — causes write hotspots.
- Use Firestore's **automatic document IDs** when possible:

```dart
final docRef = await db.collection("users").add({
  'name': 'Ada Lovelace',
  'email': '[email protected]',
  'created_at': FieldValue.serverTimestamp(),
});
print('Created document with ID: ${docRef.id}');
```

- Avoid these characters in field names (require extra escaping): `.` `[` `]` `*` `` ` ``
- Use **subcollections** within documents to organize complex, hierarchical data rather than deeply nested objects.

---

## 4. Indexing

- Firestore queries are indexed by default; query performance is proportional to the result set size, not the dataset size.
- Set **collection-level index exemptions** to reduce write latency and storage costs.
- Disable Descending and Array indexing for fields that do not need them.
- Exempt string fields with long values that are not used for querying.
- Exempt fields with sequential values (e.g., timestamps) from indexing if not used in queries — avoids the 500 writes/second index limit.
- Add single-field exemptions for TTL fields.
- Exempt large array or map fields not used in queries — avoids the 40,000 index entries per document limit.

---

## 5. Read and Write Operations

### Read All Documents in a Collection

```dart
final querySnapshot = await db.collection("users").get();
for (var doc in querySnapshot.docs) {
  print("${doc.id} => ${doc.data()}");
}
```

### Query with Filters

```dart
final query = db.collection("users")
    .where("age", isGreaterThanOrEqualTo: 18)
    .orderBy("age")
    .limit(20);

final results = await query.get();
```

### Cursor-Based Pagination

```dart
// First page
final first = db.collection("cities").orderBy("name").limit(25);
final firstSnapshot = await first.get();

// Next page using last document as cursor
final lastDoc = firstSnapshot.docs.last;
final next = db.collection("cities")
    .orderBy("name")
    .startAfterDocument(lastDoc)
    .limit(25);
```

- **Do not use offsets for pagination** — use cursors to avoid retrieving and being billed for skipped documents.

### Write with Server Timestamp

```dart
await db.collection("users").doc("user_1").set({
  'name': 'Grace Hopper',
  'updated_at': FieldValue.serverTimestamp(),
});
```

### Batch Write (Atomic, Up to 500 Operations)

```dart
final batch = db.batch();
batch.set(db.collection("cities").doc("LA"), {'name': 'Los Angeles'});
batch.update(db.collection("cities").doc("SF"), {'population': 860000});
batch.delete(db.collection("cities").doc("OLD"));
await batch.commit();
```

### Transaction

```dart
await db.runTransaction((transaction) async {
  final snapshot = await transaction.get(db.collection("counters").doc("visits"));
  final currentCount = snapshot.get("count") as int;
  transaction.update(snapshot.reference, {"count": currentCount + 1});
});
```

- Execute independent operations (e.g., a document lookup and a query) **in parallel**, not sequentially.
- Be aware of write rate limits: ~1 write per second per document.
- For writing a large number of documents, use a **bulk writer** instead of the atomic batch writer.

---

## 6. Designing for Scale

- Avoid high read or write rates to **lexicographically close documents** (hotspotting).
- Avoid creating new documents with **monotonically increasing fields** (like timestamps) at a very high rate.
- Avoid **deleting documents** in a collection at a high rate.
- **Gradually increase traffic** when writing to the database at a high rate — ramp up over 5 minutes.
- Avoid queries that skip over recently deleted data — use `start_at` to find the correct start point.
- Distribute writes across different document paths to avoid contention.
- Firestore scales automatically to ~1 million concurrent connections and 10,000 writes/second.

---

## 7. Real-time Updates

```dart
final subscription = db.collection("messages")
    .where("room", isEqualTo: "general")
    .orderBy("timestamp", descending: true)
    .limit(50)
    .snapshots()
    .listen((querySnapshot) {
      for (var change in querySnapshot.docChanges) {
        switch (change.type) {
          case DocumentChangeType.added:
            print("New message: ${change.doc.data()}");
            break;
          case DocumentChangeType.modified:
            print("Modified: ${change.doc.data()}");
            break;
          case DocumentChangeType.removed:
            print("Removed: ${change.doc.id}");
            break;
        }
      }
    });

// Detach when no longer needed:
subscription.cancel();
```

- **Limit** the number of simultaneous real-time listeners.
- **Detach listeners** when they are no longer needed to avoid memory leaks and unnecessary reads.
- Use **compound queries** to filter data server-side rather than filtering on the client.
- For large collections, use queries to limit the data being listened to — never listen to an entire large collection.

---

## 8. Security

- Always use **Firebase Security Rules** to protect Firestore data.
- Security rules **do not cascade** unless a wildcard is used.
- If a query's results might contain data the user does not have access to, **the entire query fails**.

Example rules for user-owned documents:

```
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId} {
      allow read, update, delete: if request.auth != null && request.auth.uid == userId;
      allow create: if request.auth != null;
    }
  }
}
```

- **Validate user input** before submitting to Firestore to prevent injection attacks.
- Use **transactions** for operations that require atomic updates to multiple documents.
- Implement proper **error handling** for all Firestore operations.
- Never store sensitive information in Firestore without proper access controls.

---

## References

- [Cloud Firestore Flutter documentation](https://firebase.google.com/docs/firestore/quickstart?hl=en&authuser=0&platform=flutter)
- [Cloud Firestore best practices](https://firebase.google.com/docs/firestore/best-practices)
- [Cloud Firestore security rules](https://firebase.google.com/docs/firestore/security/get-started)

© Ivanna Kaceviča · MIT · evanca/flutter-ai-rules

Similar skills

All skills for Mobile →

From the same set39

The whole set →
firebase-database The firebase-database skill guides Flutter work with Firebase Realtime Database, from JSON structure and queries to live updates, offline support, and access rules. CX Codex +1 ★ 674repo stars dart-3-updates dart-3-updates — a skill for Claude Code and Codex that teaches the AI to write switch expressions, patterns, records, and modern Dart instead of old if-else chains. Helps when refactoring to Dart 3 and choosing between records and classes. CX Codex +1 ★ 674repo stars effective-dart effective-dart guides AI agents to produce idiomatic Dart and Flutter code following official style, naming, and typing conventions. CX Codex +1 ★ 674repo stars accessibility This skill walks an interface through a WCAG checklist — keyboard, screen reader, contrast, forms — and flags concrete accessibility gaps. It triggers on a11y, ARIA, alt text, focus order, contrast. CX Codex +1 ★ 674repo stars generate-images-with-firebase-ai generate-images-with-firebase-ai guides image generation and editing in Flutter via Firebase AI Logic and Gemini, troubleshooting quota errors, App Check, and blank responses. CX Codex +1 ★ 674repo stars code-review code-review reviews Flutter and Dart changes against a structured checklist, including tests, security, and code quality. Use it before merging a PR or branch. CX Codex +1 ★ 674repo stars bloc A Flutter skill for building Cubits and Blocs, choosing how state is modelled, and wiring bloc widgets into the tree. Useful when state management in a project needs one consistent shape. CX Codex +1 ★ 674repo stars firebase-auth Configures Firebase Authentication in Flutter projects. Guides email sign-in, social auth, local emulator testing, and auth state streams. CX Codex +1 ★ 674repo stars

Project sponsors

Companies that keep this analytics open