ts-fireway

library1.1.2jsnpmunverified

ts-fireway is a schema migration tool for Firestore, inspired by Flyway. Current stable version is 1.1.2, released as an npm package with no regular cadence. It provides a CLI to apply migration files (JS or TS) to Firestore, with support for dry-run, custom migration paths, project IDs, and Firestore emulator. Key differentiators: TypeScript-first with full type definitions, simple file-naming convention based on semver, and integration with Firebase Admin SDK. It is best suited for developers who want a lightweight, declarative migration workflow for Firestore without heavy ORM dependencies.

devops database

npm install ts-fireway

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TS-FIREWAY

ts-fireway

devopsjavascriptv1.1.2

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 'ts-fireway'

✗ import MigrateOptions from 'ts-fireway'

MigrateOptions is a named export (TypeScript type). Default import is not available.

migrate

✓ export async function migrate({firestore}: MigrateOptions) {...}

✗ module.exports = async function migrate({firestore}) {...}

Migration files use CommonJS (module.exports.migrate) for JS, but TypeScript files can use named export.

CLI usage

✓ npx ts-fireway migrate --path=./migrations

✗ ts-fireway migrate --path ./migrations

In older versions, the flag syntax may differ; use = for consistency.

Shows how to create a simple migration file and run it via CLI with project ID.

// Install globally or use npx // npx ts-fireway migrate --projectId=my-project --path=./migrations // Example 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: npx ts-fireway migrate --projectId=my-project --path=./migrations

Debug

Known issues

gotchaMigration file names must follow the pattern v[semver]__[description].js (or .ts). Incorrect naming will cause the migration to be ignored or errors.

fix

Rename file to match pattern, e.g., v1.0.0__initial.js

affects: >=1.0.0

gotchaThe GOOGLE_APPLICATION_CREDENTIALS environment variable must be set for authentication, or use the Firestore emulator. Without it, CLI will fail with authentication errors.

fix

Set GOOGLE_APPLICATION_CREDENTIALS to the path of your service account JSON file, or start emulator and set FIRESTORE_EMULATOR_HOST.

affects: >=1.0.0

gotchaDry-run mode (--dryrun) does not actually write to Firestore, but may still modify state if migration scripts perform side effects other than Firestore writes (e.g., Auth, Storage).

fix

Ensure migration scripts are idempotent or avoid side effects in dry-run.

affects: >=1.0.0

deprecatedVersion 1.1.2 uses Firebase Admin SDK v11 or earlier? The package does not explicitly specify dependency range, but it relies on 'firebase-admin' being installed separately.

fix

Install compatible firebase-admin version (check peerDependencies if any).

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'ts-fireway'

ts-fireway is not installed globally or not in PATH.

fix

Run 'npm install -g ts-fireway' or use 'npx ts-fireway'.

Error: Migration file 'v1.0.0__test' does not match required pattern

File name missing double underscore or semver format.

fix

Rename to 'v1.0.0__test.js' (or .ts).

Error: module.exports.migrate is not a function

Migration file exports incorrectly (e.g., default export instead of named).

fix

Use 'module.exports.migrate = async ({firestore}) => { ... }' for JS, or 'export async function migrate(...)' for TS.

Upgrade

Version history

1.1.2latest on npm

Audit

Dependencies

firebase-adminrequiredProvides Firebase Admin SDK for Firestore, Auth, and Storage access in migration scripts.

Agent activity

23 hits · last 30 days

node