fireblaze

library1.4.0jsnpmunverified

Fireblaze is a schema migration tool for Firestore, forked from the unmaintained fireway. Current stable version is 1.4.0. It provides a CLI for managing Firestore schema changes with deterministic migration ordering using semantic versioning. Supports JavaScript, TypeScript (via ts-node), and JSDoc-typed migrations. Key differentiators include async migration support, dry-run mode, emulator compatibility, and typed migration options. Release cadence is low; last update was in early 2024.

database

npm install fireblaze

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FIREBLAZE

fireblaze

databasejavascriptv1.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MigrateOptions

✓ import { MigrateOptions } from 'fireblaze'

✗ const { MigrateOptions } = require('fireblaze')

MigrateOptions is a TypeScript type. For typed migrations, import this type to use in migration function signatures.

migrate (default export)

✓ module.exports.migrate = async ({firestore}) => {}

✗ export default async ({firestore}) => {}

Migration files must export a named function 'migrate' as CommonJS module. Default export is not supported.

fireblaze CLI

✓ npx fireblaze migrate

✗ fireblaze migrate --require=ts-node

When using --require, the path must be a module name or path; use --require="ts-node/register"

Shows how to set up a minimal migration: export a migrate function using the injected Firestore instance.

// Install fireblaze globally or use npx // Set credentials process.env.GOOGLE_APPLICATION_CREDENTIALS = path/to/service-account.json; // Create a migration file: ./migrations/v1.0.0__initial.js module.exports.migrate = async ({firestore, FieldValue}) => { await firestore.collection('users').doc('admin').set({ name: 'Admin', createdAt: FieldValue.serverTimestamp() }); }; // Run migration $ npx fireblaze migrate --projectId=my-project-id

Debug

Known issues

breakingFireblaze requires Node.js >= 18 and firebase-admin >= 11; older versions may cause errors.

fix

Update Node.js to 18+ and firebase-admin to 11+.

affects: >=1.0.0

deprecatedUse of CommonJS module format is required; ESM exports are not supported.

fix

Use module.exports.migrate = async ... instead of export function migrate.

affects: >=1.0.0

gotchaMigration files must follow the name format v[semver]__[description].js (e.g., v1.0.0__init.js); otherwise they are ignored.

fix

Rename migration files to match the pattern v<semver>__<description>.js.

affects: >=1.0.0

gotchaWhen using TypeScript, ensure tsconfig.json includes ts-node configuration with "module": "commonjs".

fix

Add "ts-node": { "compilerOptions": { "module": "commonjs" } } to tsconfig.

affects: >=1.0.0

gotchaThe FIRESTORE_EMULATOR_HOST env var must be set when using emulator; otherwise migration will fail with missing project.

fix

Run export FIRESTORE_EMULATOR_HOST="localhost:8080" before migrating locally.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'ts-node/register'

ts-node not installed locally or globally.

fix

Install ts-node as a dev dependency: npm install --save-dev ts-node

Error: Migration file 'v1.0__init.js' does not match required pattern

Migration filename does not include both version and description with double underscore.

fix

Rename to 'v1.0.0__init.js' (include patch version 0 and double underscore).

TypeError: fireblaze is not a function

Trying to import fireblaze as a library in code instead of using CLI.

fix

Fireblaze is a CLI tool; run `npx fireblaze migrate` from terminal, not in code.

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

firebase-adminrequiredRequired to connect to Firestore in migration scripts

Agent activity

7 hits · last 30 days

node

Resources

githubssh://git@github.com/jackall3n/fireblaze ↗

packagefireblaze ↗

homepagehttps://github.com/jackall3n/fireblaze#readme ↗