Jeremy Firestore Plugin

Production-ready Firebase/Firestore operations for Claude Code

Build, manage, and optimize Firebase/Firestore databases with AI-powered agents that handle CRUD operations, security rules, batch processing, migrations, and performance monitoring.

Features

Core Capabilities

• CRUD Operations - Create, read, update, delete with batch support
• Security Rules - Generate, validate, and deploy Firestore security rules
• Data Migration - Migrate data between collections, projects, or environments
• Batch Operations - Process thousands of documents efficiently
• Cost Optimization - Analyze and reduce Firebase costs
• Performance Monitoring - Track queries, indexes, and bottlenecks
• Cloud Functions Integration - Trigger and manage Cloud Functions
• Collection Management - Schema validation, indexing, and organization

AI Agents

• firebase-operations-agent - CRUD, queries, batch operations
• firestore-security-agent - Security rules generation and validation
• firestore-migration-agent - Data migration and transformation
• firestore-optimizer-agent - Performance and cost optimization

Commands

• /firestore-setup - Initialize Firebase SDK and credentials
• /firestore-query - Interactive query builder
• /firestore-migrate - Guided migration workflow

Quick Start

Installation

# Install the plugin
/plugin install jeremy-firestore@claude-code-plugins-plus

# Initialize Firebase in your project
/firestore-setup

Prerequisites

1. Firebase Project - Create at https://console.firebase.google.com
2. Service Account - Download JSON key from Project Settings > Service Accounts
3. Node.js - Version 18+ with npm/pnpm/yarn

First-Time Setup

# 1. Install Firebase Admin SDK
npm install firebase-admin

# 2. Set environment variable
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/serviceAccountKey.json"

# 3. Run setup command
/firestore-setup

Usage Examples

Example 1: CRUD Operations

// Create documents
"Create a new user document in the 'users' collection"

Agent creates:
{
  uid: "user123",
  email: "[email protected]",
  createdAt: Timestamp.now(),
  role: "user"
}

// Read with queries
"Get all users created in the last 7 days"

Agent executes:
db.collection('users')
  .where('createdAt', '>=', sevenDaysAgo)
  .orderBy('createdAt', 'desc')
  .get()

// Update documents
"Update user123's role to 'admin'"

Agent updates:
db.collection('users').doc('user123').update({
  role: 'admin',
  updatedAt: Timestamp.now()
})

// Delete with safety checks
"Delete all test users but keep production data"

Agent:
1. Validates query won't delete production data
2. Shows preview of documents to delete
3. Asks for confirmation
4. Executes batch delete

Example 2: Security Rules

# Generate security rules for a users collection
"Create security rules for the users collection where:
- Users can read their own document
- Only admins can write
- Email field is required and must be a valid email"

Agent generates:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId} {
      // Users can read their own document
      allow read: if request.auth != null && request.auth.uid == userId;

      // Only admins can write
      allow write: if request.auth != null &&
                      get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == 'admin';

      // Validation
      allow create, update: if request.resource.data.email is string &&
                               request.resource.data.email.matches('^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$');
    }
  }
}

Example 3: Data Migration

# Migrate data between environments
"Migrate all users from staging to production, but anonymize email addresses"

Agent workflow:

1. Connects to staging - Reads source collection
2. Transforms data - Anonymizes PII fields
3. Validates - Checks schema compatibility
4. Batch writes - Writes to production in chunks of 500
5. Verifies - Confirms document counts match
6. Reports - Shows migration summary

Example 4: Batch Operations

# Update 10,000 documents efficiently
"Add a 'verified: false' field to all users who registered before 2024"

Agent executes:

• Queries in batches of 500 documents
• Uses batch writes for efficiency (reduces costs 10x)
• Handles rate limits automatically
• Shows progress updates
• Reports total documents updated

Example 5: Performance Optimization

# Analyze slow queries
"Analyze the performance of my Firestore queries and suggest optimizations"

Agent analyzes:

• Missing indexes - Identifies composite indexes needed
• Query patterns - Finds inefficient queries
• Collection structure - Suggests denormalization opportunities
• Read/write costs - Calculates monthly costs
• Recommendations - Provides actionable improvements

Agent Reference

firebase-operations-agent

Purpose: Handle all Firestore CRUD operations, queries, and batch processing

Use when:

• Creating, reading, updating, or deleting documents
• Running complex queries with filters and ordering
• Batch operations on multiple documents
• Collection management

Trigger phrases:

• "create a document in..."
• "query the users collection..."
• "batch update all documents where..."
• "delete documents matching..."

Example:

User: "Get the 10 most recent orders for user123"

Agent:
1. Validates collection exists
2. Builds query: orders.where('userId', '==', 'user123').orderBy('createdAt', 'desc').limit(10)
3. Executes query
4. Returns formatted results

firestore-security-agent

Purpose: Generate, validate, and deploy Firestore security rules

Use when:

• Creating new security rules
• Validating existing rules
• Troubleshooting permission errors
• Implementing authentication patterns

Trigger phrases:

• "create security rules for..."
• "validate my firestore rules..."
• "fix permission denied error..."
• "implement role-based access..."

Example:

User: "Create rules for a chat app with public rooms and private messages"

Agent:
1. Analyzes data model (rooms, messages collections)
2. Generates rules with:
   - Public read for rooms
   - Authenticated write for rooms
   - Private message access (sender/recipient only)
3. Adds validation (message length, required fields)
4. Tests rules with sample scenarios

firestore-migration-agent

Purpose: Migrate data between collections, projects, or environments

Use when:

• Moving data between environments (staging → production)
• Restructuring collections
• Backfilling data
• Importing/exporting data

Trigger phrases:

• "migrate data from..."
• "copy collection to..."
• "restructure the users collection..."
• "backfill missing fields..."

Example:

User: "Migrate users collection to a new structure with nested addresses"

Agent:
1. Reads existing user documents
2. Transforms: { address: "123 Main St" } → { address: { street: "123 Main St", city: "", zip: "" } }
3. Validates transformation
4. Writes to new collection
5. Verifies data integrity

firestore-optimizer-agent

Purpose: Optimize Firestore performance and reduce costs

Use when:

• Slow queries need optimization
• Monthly costs are too high
• Need index recommendations
• Want to analyze usage patterns

Trigger phrases:

• "optimize my firestore performance..."
• "reduce firebase costs..."
• "why is this query slow..."
• "analyze my firestore usage..."

Example:

User: "Why is my users query so slow?"

Agent analyzes:
1. Query structure: .where('status', '==', 'active').where('createdAt', '>', date).orderBy('name')
2. Identifies: Missing composite index for (status, createdAt, name)
3. Calculates: 15,000 documents scanned for 100 results = 150x overhead
4. Recommends: Create index or denormalize data
5. Estimates: 50% cost reduction with index

Configuration

Environment Variables

# Required
GOOGLE_APPLICATION_CREDENTIALS="/path/to/serviceAccountKey.json"

# Optional
FIREBASE_PROJECT_ID="your-project-id"           # Auto-detected from credentials
FIRESTORE_EMULATOR_HOST="localhost:8080"        # For local development
FIREBASE_DATABASE_URL="https://your-db.firebaseio.com"  # For Realtime Database

firestore.config.js

module.exports = {
  // Project configuration
  projectId: 'your-project-id',

  // Batch operation settings
  batchSize: 500,                    // Documents per batch write
  maxConcurrentBatches: 3,           // Parallel batch operations

  // Query settings
  defaultLimit: 100,                 // Default query limit
  maxLimit: 1000,                    // Maximum allowed limit

  // Cost optimization
  enableCaching: true,               // Cache frequently read documents
  cacheTTL: 300,                     // Cache time-to-live (seconds)

  // Migration settings
  migrationBatchSize: 500,           // Documents per migration batch
  validateBeforeMigration: true,     // Validate data before migrating

  // Security
  allowDangerousOperations: false,   // Require confirmation for deletes
  dryRun: false                      // Preview changes without executing
};

Best Practices

Security Rules

• Never allow open access - Always require authentication
• Validate all writes - Check field types and values
• Limit read scope - Only allow reading necessary data
• Test rules thoroughly - Use Firebase Emulator Suite

Performance

• Use indexes - Create composite indexes for complex queries
• Batch operations - Use batch writes for multiple documents
• Denormalize data - Duplicate data to avoid joins
• Paginate results - Use cursor-based pagination for large datasets

Cost Optimization

• Cache frequently read data - Use in-memory caching
• Minimize document reads - Use select() to read specific fields
• Archive old data - Move historical data to Cloud Storage
• Monitor usage - Set up billing alerts

Data Modeling

• Keep documents small - Max 1MB per document
• Use subcollections - For nested data hierarchies
• Plan for scale - Design for millions of documents
• Avoid hot documents - Distribute writes across documents

Common Patterns

Pattern 1: User Profiles with Privacy

// Collection structure
users/{userId}
  - public: { name, avatar, bio }        // Anyone can read
  - private: { email, phone, address }   // Only user can read
  - settings: { notifications, privacy } // Only user can read/write

Pattern 2: Real-time Chat

// Collection structure
rooms/{roomId}
  - metadata: { name, createdAt, memberCount }
  - members/{userId}: { joinedAt, role }

messages/{messageId}
  - roomId, userId, text, createdAt

// Query optimization
- Index: (roomId, createdAt) for fetching messages
- Denormalize: Store last message in room metadata

Pattern 3: E-commerce Orders

// Collection structure
orders/{orderId}
  - userId, status, total, createdAt
  - items: [ { productId, quantity, price } ]  // Embedded array

// Status workflow
pending → processing → shipped → delivered

// Indexes
- (userId, createdAt) - User order history
- (status, createdAt) - Admin order management

Troubleshooting

Error: Permission Denied

# Check security rules
firebase firestore:rules:get

# Test rules locally
firebase emulators:start --only firestore

# Ask agent for help
"Why am I getting permission denied when reading /users/user123?"

Error: Missing Index

# Agent will detect and create index automatically
"Create an index for querying users by (status, createdAt)"

# Or manually
firebase firestore:indexes

# Deploy
firebase deploy --only firestore:indexes

Error: Rate Limits

# Agent handles rate limits automatically with exponential backoff
# For custom handling:
"Batch update 50,000 users with rate limit handling"

Error: Invalid Credentials

# Verify service account
gcloud auth application-default login

# Or set environment variable
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/serviceAccountKey.json"

# Verify
firebase projects:list

Advanced Features

Cloud Functions Integration

// Trigger Cloud Functions from Firestore
"Create a function that sends an email when a new user signs up"

Agent creates:
exports.sendWelcomeEmail = functions.firestore
  .document('users/{userId}')
  .onCreate(async (snap, context) => {
    const user = snap.data();
    await sendEmail(user.email, 'Welcome!');
  });

Backup and Restore

# Export collection
"Export the users collection to JSON"

# Import data
"Import users from backup.json to the staging environment"

# Schedule backups
"Set up daily backups of all collections to Cloud Storage"

Multi-Project Management

# Switch between projects
"Use the staging Firebase project"
"Switch back to production"

# Copy data between projects
"Copy the test users from staging to production"

Performance Benchmarks

| Operation | Without Plugin | With Plugin | Improvement | |-----------|----------------|-------------|-------------| | Single document write | 50ms | 45ms | 1.1x | | Batch write (500 docs) | 25s | 2.5s | 10x | | Complex query | 5s | 500ms | 10x (with index) | | Migration (10k docs) | Manual 2hrs | 5 minutes | 24x | | Security rule generation | Manual 30min | 2 minutes | 15x |

Integration Examples

Next.js App

// pages/api/users.js
import admin from 'firebase-admin';

// Agent sets up admin SDK automatically
export default async function handler(req, res) {
  const users = await admin.firestore()
    .collection('users')
    .limit(10)
    .get();

  res.json(users.docs.map(doc => doc.data()));
}

React App

// hooks/useFirestore.js
import { getFirestore, collection, query, where } from 'firebase/firestore';

// Agent generates custom hooks
export function useUserOrders(userId) {
  const [orders, setOrders] = useState([]);

  useEffect(() => {
    const q = query(
      collection(db, 'orders'),
      where('userId', '==', userId)
    );
    // ... subscribe to query
  }, [userId]);

  return orders;
}

Cloud Functions

// functions/index.js
const admin = require('firebase-admin');
admin.initializeApp();

// Agent creates Cloud Functions
exports.onUserCreate = functions.firestore
  .document('users/{userId}')
  .onCreate(async (snap) => {
    // Send welcome email, create profile, etc.
  });

Resources

Firebase Documentation

• Firestore Documentation
• Security Rules
• Best Practices

Plugin Resources

• GitHub Repository
• Issue Tracker
• Marketplace

Community

• Discord (#claude-code channel)
• GitHub Discussions

License

MIT License - see LICENSE file for details

Support

Need help? Open an issue on GitHub or ask in Discord!

Made with by Jeremy Longshore