{"id":46913,"library":"alter-firestore","title":"alter-firestore","description":"A CLI tool for managing Firestore schema migrations and data alterations using TypeScript files. v2.1.8 requires Node.js >=21.0.0 and is Pure ESM (package.json must have type:module). Supports migration up/down, rollback, refresh, and custom alter scripts. Runs against Firestore emulator or production projects via Firebase Admin SDK. Ships TypeScript definitions. The tool exports ActionArg types for migration/alter functions.","status":"active","version":"2.1.8","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/cilly-yllic/alter-firestore","tags":["javascript","cli","firestore","migration","typescript"],"install":[{"cmd":"npm install alter-firestore","lang":"bash","label":"npm"},{"cmd":"yarn add alter-firestore","lang":"bash","label":"yarn"},{"cmd":"pnpm add alter-firestore","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used to interact with Firestore (getDoc, create, recursiveDelete)","package":"firebase-admin","optional":false},{"reason":"Required to execute TypeScript migration/alter files via ts-node-esm","package":"ts-node","optional":true}],"imports":[{"note":"ActionArg is not exported from the main entry; must use 'alter-firestore/types/command' subpath.","wrong":"import { ActionArg } from 'alter-firestore'","symbol":"ActionArg","correct":"import { ActionArg } from 'alter-firestore/types/command'"},{"note":"Options types are in the 'types/options' subpath.","wrong":"import { MigrateOptions } from 'alter-firestore'","symbol":"MigrateOptions","correct":"import { MigrateOptions } from 'alter-firestore/types/options'"},{"note":"This package is Pure ESM and cannot be used with CommonJS require(). Package.json must contain 'type': 'module'.","wrong":"const alter = require('alter-firestore')","symbol":"require('alter-firestore')","correct":"import ... from 'alter-firestore'"}],"quickstart":{"code":"// Set package.json type to module\n// package.json: { \"type\": \"module\" }\n// Install\n// npm i alter-firestore\n// Install ts-node for TypeScript execution\n// npm i -D ts-node\n\n// Create .alfsrc.js\nexport default {\n  emulator: {\n    options: { projectId: 'demo-project' },\n    ports: { firestore: '8080' },\n  },\n  credentialPaths: { staging: './staging-key.json' },\n  migrations: { collectionName: 'migrations', directoryPath: 'migrations' },\n};\n\n// Create a migration file: migrations/001_create_users.ts\nimport { ActionArg } from 'alter-firestore/types/command';\nimport { MigrateOptions } from 'alter-firestore/types/options';\n\nexport const up = async ({ firestore }: ActionArg<MigrateOptions>) => {\n  return firestore.create('users', 'user1', { name: 'Alice' });\n};\n\nexport const down = async ({ firestore }: ActionArg<MigrateOptions>) => {\n  const ref = firestore.doc('users/user1');\n  return firestore.recursiveDelete('users', ref);\n};\n\n// Run migration against emulator\n// npm run alfs -- migrate\n// or: node --loader ts-node/esm node_modules/.bin/alfs migrate","lang":"typescript","description":"Setup and create a basic migration file that creates a document (up) and deletes it (down), then run against the Firestore emulator."},"warnings":[{"fix":"Update Node.js to 21.x or 22.x. Check with 'node --version'.","message":"Node.js version must be >=21.0.0 and >=22.0.0. Older versions will cause runtime errors.","severity":"breaking","affected_versions":"<21.0.0"},{"fix":"Set 'type': 'module' in your package.json. Use import syntax instead of require().","message":"Package is Pure ESM and cannot be loaded with require(). CommonJS projects will fail with ERR_REQUIRE_ESM.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use import { ActionArg } from 'alter-firestore/types/command'.","message":"ActionArg and options types must be imported from subpaths like 'alter-firestore/types/command', not from the main export.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"search_vec":"'21.0.0':21 'actionarg':57 'admin':49 'alter':2,14,38 'alter-firestor':1 'cli':5,63 'custom':37 'data':13 'definit':53 'emul':43 'esm':25 'export':56 'file':17 'firebas':48 'firestor':3,9,42,64 'function':61 'javascript':62 'manag':8 'migrat':11,32,65 'migration/alter':60 'modul':30 'must':27 'node.js':20 'package.json':26 'product':45 'project':46 'pure':24 'refresh':35 'requir':19 'rollback':34 'run':40 'schema':10 'script':39 'sdk':50 'ship':51 'support':31 'tool':6,55 'type':29,58 'typescript':16,52,66 'up/down':33 'use':15 'v2.1.8':18 'via':47","created_at":"2026-06-07T16:48:12.717338+00:00","updated_at":"2026-06-07T16:48:12.717338+00:00","problems":[{"fix":"Add 'type': 'module' to package.json or dynamically import().","cause":"Package is Pure ESM but loaded with require() in a CommonJS context.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module"},{"fix":"Ensure .alfsrc.js exists with proper fields for your environment (emulator or credentialPaths).","cause":".alfsrc.js is missing or incorrectly configured, or a required credential path is not set.","error":"TypeError: Cannot read properties of undefined (reading '…')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/cilly-yllic/alter-firestore#readme","github":"ssh://git@github.com/cilly-yllic/alter-firestore","docs":null,"changelog":null,"pypi":null,"npm":"alter-firestore","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}