firestore-indexes-diff

🔍 Firestore Indexes Diff

A modern CLI tool that displays differences between two Firestore index configuration files, helping you identify missing indexes when deploying across environments.

✨ Features

• 🚀 Compare Firestore index configurations between environments
• 📊 Identify missing indexes and field overrides
• 💡 Clean, colorful CLI output with progress indicators
• 📁 Export differences to JSON files for further analysis
• 🔧 Simple command-line interface

📋 Prerequisites

Ensure you have your Firestore index configuration files ready. You can export them using the Cloud Firestore Index Definition Reference.

🚀 Quick Start

Using pnpm dlx (Recommended)

pnpm dlx firestore-indexes-diff --source dev.json --target prod.json
# npx firestore-indexes-diff --source dev.json --target prod.json
# yarn dlx firestore-indexes-diff --source dev.json --target prod.json

Global Installation

pnpm add -g firestore-indexes-diff
# npm install -g firestore-indexes-diff
# yarn global add firestore-indexes-diff

diff-indexes --source dev.json --target prod.json

⚙️ Options

Option	Alias	Type	Required	Description
--source	-s	string	✅	Source indexes file path
--target	-t	string	✅	Target indexes file path
--version	-v			Show version number
--help	-h			Show help

📤 Output

The tool generates the following output files in your current directory:

• diff-indexes.json - Contains missing indexes
• diff-field-overrides.json - Contains missing field overrides

🔄 Workflow Examples

Development to Production Comparison

# Compare your development environment against production
pnpm dlx firestore-indexes-diff --source dev-indexes.json --target prod-indexes.json

Staging Environment Sync

# Ensure staging has all the indexes from development
pnpm dlx firestore-indexes-diff --source dev-indexes.json --target staging-indexes.json

CI/CD Integration

# In your CI pipeline, validate index completeness
- name: Check Firestore Index Completeness
  run: |
    # Export current production indexes
    firebase firestore:indexes > prod-indexes.json
    
    # Export your project's indexes
    firebase firestore:indexes --project ${{ env.PROJECT_ID }} > current-indexes.json
    
    # Check for missing indexes
    pnpm dlx firestore-indexes-diff --source current-indexes.json --target prod-indexes.json
    
    # Fail if differences found
    if [ -f "diff-indexes.json" ]; then
      echo "Missing indexes detected!"
      cat diff-indexes.json
      exit 1
    fi

Multi-Environment Validation

# Check multiple environments in sequence
environments=("dev" "staging" "prod")
for env in "${environments[@]}"; do
  echo "Checking $env environment..."
  pnpm dlx firestore-indexes-diff \
    --source master-indexes.json \
    --target "$env-indexes.json"
done

🛠️ Development

# Clone the repository
git clone https://github.com/omar-dulaimi/firestore-indexes-diff.git
cd firestore-indexes-diff

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run in development mode
pnpm run dev

📝 License

MIT © Omar Dulaimi

Changelog

1.0.1 (2025-10-16)

Bug Fixes

• release: ensure npm verifyConditions sees package/package.json (track stub and adjust .gitignore) (55eb75e)
• release: harden package.sh (idempotent rm, typo fix) (00ca0f9)

Features

• add GitHub Actions CI/CD workflows (b106297)
• modernize project with comprehensive tooling improvements (e8ecf36)