npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@schorts/firestore-migrator

v1.0.0

Published

Declarative migration tool for Cloud Firestore. Define field additions, removals, and transforms in simple migration files, then apply or roll them back with a single CLI command.

Downloads

258

Readme

@schorts/firestore-migrator

Declarative migration tool for Cloud Firestore. Define field additions, removals, and transforms in simple migration files, then apply or roll them back with a single CLI command.

Features:

  • Declarative up / down operations (add, remove, update)
  • Before-image snapshots for exact restore on failure and rollback
  • Optional live schema file refreshed after migrate/rollback
  • Project config via firestore-migrator.toml, .env, and CLI flags

Requires Node.js ≥ 18 and a Firebase service account (or Application Default Credentials).

Install

npm install -D @schorts/firestore-migrator

The CLI binary is always firestore-migrator.

Quick start

# 0. Config + credentials
firestore-migrator init
# put secrets in .env (auto-loaded) or set GOOGLE_APPLICATION_CREDENTIALS

# 1. Create a migration
firestore-migrator generate add-user-status users

# 2. Edit migrations/<timestamp>_add-user-status.js
#    Fill in up / down operations

# 3. Preview
firestore-migrator migrate --dry-run

# 4. Apply
firestore-migrator migrate

# 5. Status
firestore-migrator status

# 6. Schema (optional)
firestore-migrator schema
firestore-migrator schema users orders

# 7. Roll back last migration (or multiple steps)
firestore-migrator rollback
firestore-migrator rollback 2       # or: firestore-migrator rollback --steps 2

CLI

firestore-migrator init
firestore-migrator generate <name> [collection]
firestore-migrator migrate   [--dry-run] [--only <name|id>] [--skip-schema]
firestore-migrator rollback  [steps] [--steps <n>] [--only <name|id>] [--dry-run] [--skip-schema]
firestore-migrator schema    [collections...] [--no-merge]
firestore-migrator status

Commands

| Command | Description | |---------|-------------| | init | Create firestore-migrator.toml in the current directory | | generate | Create a new timestamped migration file | | migrate | Apply all pending migrations (or one with --only) | | rollback | Roll back the latest applied migration(s) ([steps], --steps <n>, or --only) | | schema | Sample collections and write firestore.schema.json | | status | List migrations and applied / pending state |

Global options

| Option | Description | |--------|-------------| | --config <path> | Path to TOML config (default: ./firestore-migrator.toml if present) | | --env-file <path> | Path to .env file (default: ./.env, then ./.env.local) | | --env-override | Let .env values override existing environment variables | | -d, --migrations-dir <path> | Directory with migration files (default: ./migrations) | | -t, --tracking-collection <name> | Collection that records applied migrations (default: __migrations) | | --schema-path <path> | Schema output path (default: ./firestore.schema.json) | | --snapshots-dir <path> | Before-image snapshots directory (default: <migrationsDir>/.snapshots) | | --project-id <id> | GCP / Firebase project id | | -c, --credentials <path> | Path to service account JSON | | --only <name|id> | Apply or roll back only the specified migration | | --steps <n> | Rollback only: number of migrations to revert (default: 1) | | --dry-run | Simulate without writing | | --skip-schema | Do not refresh schema after migrate/rollback | | --no-merge | schema only: replace the schema file instead of merging | | --force | init only: overwrite an existing config file | | -o, --output <path> | init only: custom path for the config file |

Configuration

Precedence (highest → lowest)

  1. CLI flags
  2. Environment variables (including values loaded from .env)
  3. firestore-migrator.toml
  4. Built-in defaults

.env files

loadConfig() loads ./.env, then ./.env.local if .env is missing. Existing shell/CI variables are not overwritten unless you pass --env-override.

# .env
FIREBASE_PROJECT_ID=my-project
GOOGLE_APPLICATION_CREDENTIALS=./serviceAccount.json
[email protected]
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
firestore-migrator migrate
firestore-migrator migrate --env-file ./config/.env.staging
firestore-migrator migrate --env-override

.env is listed in .gitignore by default.

firestore-migrator init

firestore-migrator init
firestore-migrator init --force
firestore-migrator init -o ./config/prod.toml

Example firestore-migrator.toml:

# paths & behaviour
migrations_dir       = "migrations"
tracking_collection  = "__migrations"
schema_path          = "firestore.schema.json"
snapshots_dir        = "migrations/.snapshots"
skip_schema          = false

# firebase
project_id  = "my-firebase-project"
credentials = "./serviceAccount.json"
# or interpolate from the environment:
# credentials = "${GOOGLE_APPLICATION_CREDENTIALS}"
# project_id  = "$FIREBASE_PROJECT_ID"

# map config keys → env var *names* (values stay in the environment)
[env]
project_id   = "FIREBASE_PROJECT_ID"
credentials  = "GOOGLE_APPLICATION_CREDENTIALS"
private_key  = "FIREBASE_PRIVATE_KEY"
client_email = "FIREBASE_CLIENT_EMAIL"

String values support ${VAR} and $VAR expansion. The optional [env] section points keys at env var names so secrets never need to live in the file.

Environment variables

| Variable | Purpose | |----------|---------| | GOOGLE_APPLICATION_CREDENTIALS | Path to service account JSON | | FIREBASE_PROJECT_ID / GCLOUD_PROJECT / GOOGLE_CLOUD_PROJECT | Project id | | FIREBASE_PRIVATE_KEY | Inline private key (use with client email) | | FIREBASE_CLIENT_EMAIL | Service account email | | FIRESTORE_MIGRATIONS_DIR | Migrations directory | | FIRESTORE_MIGRATIONS_TRACKING | Tracking collection name | | FIRESTORE_SCHEMA_PATH | Schema file path | | FIRESTORE_SNAPSHOTS_DIR | Snapshots directory | | FIRESTORE_SKIP_SCHEMA | 1 or true to skip schema refresh |

Migration file format

Files are ESM modules named YYYYMMDDHHmmss_<slug>.js under the migrations directory.

export default {
  id: "20260804052509_add-user-status",
  description: "add user status",
  collection: "users",

  up: {
    add: {
      status: { default: "active" },
      fullName: {
        from: (doc) => `${doc.firstName || ""} ${doc.lastName || ""}`.trim(),
      },
    },
    remove: ["legacyFlag"],
    update: {
      email: (doc) => (doc.email || "").toLowerCase(),
    },
  },

  // Used when no snapshot is available (fallback)
  down: {
    add: {},
    remove: ["status", "fullName"],
    update: {},
  },
};

Operations

| Key | Purpose | |-----|---------| | add | Add fields. Use { default: value } or { from: (doc) => value }. Existing fields are left untouched (idempotent). | | remove | Array of field names to delete (FieldValue.delete()). | | update | Map of field → (doc) => newValue transforms. Returning undefined leaves the field unchanged. |

Prefer keeping a useful down block even when snapshots exist — it is the fallback if the snapshot file is missing.

Snapshots, failure & rollback

During migrate, before each document is updated a before-image is written to:

<migrationsDir>/.snapshots/<migrationId>.json

Before-images are first appended to a temporary .journal file before their writes are queued; the journal is folded into the snapshot when the migration completes and is read during recovery.

Example:

{
  "migrationId": "20260905120000_add-status",
  "collection": "users",
  "documents": {
    "user_1": {
      "status": { "__absent": true },
      "email": "[email protected]",
      "legacyFlag": true
    }
  }
}

| Situation | Behavior | |-----------|----------| | Migrate fails mid-way | Restores only committed docs from the snapshot (exact previous values), then deletes the snapshot. Migration is not marked applied. | | Manual rollback | Prefers snapshot restore for the whole migration; deletes snapshot when done | | No snapshot | Falls back to declarative down | | No snapshot and no down | Cannot compensate / roll back — warning or error |

  • __absent means the field was added by up and should be deleted on restore.
  • Timestamps, GeoPoints, references, and bytes are serialized so they can be written back.
  • Keep migrations/.snapshots/ out of git if snapshots may contain sensitive data (listed in .gitignore).

Configure the directory via:

snapshots_dir = "migrations/.snapshots"

or FIRESTORE_SNAPSHOTS_DIR / --snapshots-dir.

Schema

# All root collections (skips tracking collection)
firestore-migrator schema

# Specific collections
firestore-migrator schema users orders

# Custom path / replace instead of merge
firestore-migrator schema --schema-path ./schemas/app.json --no-merge

After a successful migrate or rollback (not dry-run), the schema is refreshed for every collection those migrations touched and merged into the schema file. Disable with --skip-schema or skip_schema = true in the TOML config.

Example firestore.schema.json:

{
  "version": 1,
  "updatedAt": "2026-08-04T21:00:00.000Z",
  "collections": {
    "users": {
      "empty": false,
      "sampleId": "abc123",
      "updatedAt": "2026-08-04T21:00:00.000Z",
      "fields": {
        "email": "string",
        "age": "number",
        "active": "boolean",
        "tags": { "type": "array", "items": "string" },
        "profile": {
          "type": "map",
          "fields": {
            "displayName": "string",
            "score": "number"
          }
        },
        "createdAt": "timestamp"
      }
    }
  }
}

Inferred types: string, number, boolean, null, timestamp, geopoint, reference, bytes, array, map.

One document is sampled per collection (limit(1)). Empty collections are recorded as "empty": true.

How it works

  1. .env / .env.local is loaded into process.env (if present).
  2. Migration files live in ./migrations (or migrations_dir) and are named YYYYMMDDHHmmss_<slug>.js.
  3. Applied migrations are recorded in a tracking collection (__migrations by default).
  4. migrate runs pending files in timestamp order, applying up with BulkWriter and writing before-image snapshots.
  5. On failure mid-migration, committed docs are restored from the snapshot. The migration is not marked applied.
  6. rollback restores from the snapshot when present; otherwise uses declarative down. Tracking record is removed.
  7. Schema is optionally refreshed for touched collections after migrate/rollback.

Collections are paginated so large datasets stay memory-safe. BulkWriter manages write scheduling. add skips fields that already exist.

Programmatic usage

import {
  generateMigration,
  runMigrate,
  runRollback,
  runStatus,
  runSchema,
  runInitConfig,
  loadConfig,
  loadEnvFile,
  applyOperations,
  createSnapshotStore,
  restoreFromSnapshot,
  FieldValue,
} from "@schorts/firestore-migrator";

loadEnvFile(); // optional; also runs inside loadConfig()
runInitConfig();

await runMigrate({ dryRun: true });
await runSchema({}, ["users", "orders"]);
await runRollback({ steps: 1 });

Pass the same option names as the CLI flags (camelCase), e.g. migrationsDir, schemaPath, snapshotsDir, projectId, credentials, skipSchema, config, envFile, envOverride.

License

LGPL-3.0-or-later