Features

• Fast: Parallel insertions with configurable concurrency.
• Efficient: Support for Firestore Batch Writes to reduce write pressure.
• Flexible: Specify document IDs via a field or let Firestore auto-generate them.
• Safe: Preview transformations with --dry-run mode.
• Robust: Automatic retries with exponential backoff for transient failures.
• Timestamps: Native support for Firestore Timestamps using special markers.

Installation

Via Cargo (Recommended)

If you have Rust installed, you can install with cargo:

cargo install json-firestore-seed

Via Homebrew

brew tap shayyz-code/tap
brew install json-firestore-seed

Via NPM

npm install -g json-firestore-seed

Via GitHub Releases

Download the latest binary for your platform from the Releases page.

Authentication

By default, the tool looks for a service account key file named application_default_credentials.json in the current directory.

1. Firebase Console → Project Settings → Service Accounts
2. Click Generate new private key
3. Save it and provide the path using the -k or --credentials flag.

Usage

json-firestore-seed -j data.json -c users -p my-firestore-project

Parameters

| Flag | Long Form | Default | Description | | ---- | --------------- | ---------------------------------------- | --------------------------------------- | | -j | --json | (required) | Path to JSON file (must be an array) | | -c | --collection | (required) | Target Firestore collection name | | -p | --project | (required) | Google Cloud Project ID | | -k | --credentials | ./application_default_credentials.json | Path to service account JSON key file | | -i | --id-field | (auto-generate) | Field in JSON to use as document ID | | -d | --dry-run | false | Preview transformations without writing | | -m | --concurrency | 4 | Number of parallel write tasks | | -r | --retries | 3 | Number of retries for failed writes | | -b | --batch-size | 1 | Items per Firestore batch (max 500) |

JSON Format & Timestamps

The input JSON must be an array of objects.

Firestore Timestamp Markers

• __fire_ts_now__: Sets the field to the current server time.
• { "__fire_ts_from_date__": "YYYY-MM-DD HH:MM:SS" }: Parses a specific date string. Supports RFC3339 and common naive formats.

Example:

[
    {
        "id": "user_1",
        "name": "Alice",
        "created_at": { "__fire_ts_from_date__": "2024-11-11T11:21:56Z" },
        "updated_at": "__fire_ts_now__"
    }
]

Troubleshooting

"Authentication failed"

• Ensure your service account key is valid and has the Cloud Datastore User or Firebase Firestore Admin role.
• Verify the path to your credentials file using --credentials.

"Permission Denied"

• Check if the Project ID matches your Firestore instance.
• Ensure the service account has write access to the specific collection.

"JSON must be an array"

• The root element of your JSON file must be a [ (array). Individual objects are not supported as top-level elements.

Contributing

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'feat: add amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

License

MIT License — free for personal & commercial use.

Copyright (c) 2025 shayyz-code.