developing-firebase-tools

Developing Firebase Tools

This skill guides you through setting up branches or git worktrees, managing dependencies, testing changes, and submitting PRs for the firebase-tools repository.

Repository Setup & Workspace Management

When working on a feature or bug fix, you can work either in a dedicated Git branch in your current repository clone, or use Git worktrees to isolate multiple tasks or parallel changes.

• Option A: Direct Branch (Single task)

  git checkout main
  git pull origin main
  git checkout -b {branch_name}
  

• Option B: Git Worktree (Recommended for isolating parallel tasks or agent workflows) Create a worktree outside or sibling to the repository:

  git fetch origin main
  git worktree add -b {branch_name} ../firebase-tools-worktrees/{branch_name} origin/main
  cd ../firebase-tools-worktrees/{branch_name}
  

  Tip: For small changes in a new worktree, you can avoid a full npm install by symlinking the primary clone's dependencies:

  ln -sfn ../firebase-tools/node_modules node_modules
  

---

Environment & Dependency Notes

• Node.js Versions:
  • The CLI supports Node 20+.
  • When updating dependencies or modifying package.json, synchronize npm-shrinkwrap.json using Node 24 (nvm use 24 && npm install --package-lock-only or npm install --package-lock-only under Node 24) and commit the diff to ensure the CI check-package-lock (24) check passes.
• Code Formatting & Linting:
  • The repository enforces Prettier formatting in CI. Run Prettier on changed files (including .yaml and .json) before committing/pushing:

    npm run format
    # or to verify without writing:
    npx prettier --check path/to/changed/files
    

  • Verify lint checks:

    npm run lint
    

• ESM vs CommonJS Dependencies:
  • The Firebase CLI compiles to CommonJS, and the standalone binary bundles Node 20.x (which lacks unflagged require(esm) support). CI tests both Node 20 and Node 24.
  • If a dependency is ESM-only ("type": "module", no require export), do not import it statically at the top level of files that are loaded eagerly during CLI initialization.
  • Instead, load ESM-only dependencies lazily using dynamic import() (see src/streamJson.ts for an example using new Function("url", "return import(url)") to avoid ts-node rewriting import() to require() in Mocha tests).

---

Workflow: Development & Verification

1. Implement Changes: Make the necessary changes following the repository's coding standards.

2. Update CHANGELOG.md (if applicable): For user-facing changes (new features, bug fixes, deprecations), add an entry to CHANGELOG.md:

   • Start with a past-tense verb (e.g., Fixed, Added, Updated).
   • Do not include bracketed annotations such as [fixed] or [added].
   • End with (#<issue_number>) if the change addresses a GitHub issue.
   • Example: - Fixed `ERR_REQUIRE_ESM` crash in the standalone binary. (#11168)

3. Verify Code Compiles & Tests Pass: Ensure you are in the workspace or worktree directory, then run:

   npm run build
   npm test
   

   To run a specific test file:

   npm test -- src/test/path/to/test.spec.ts
   

4. Commit Changes:

   git add .
   git commit -m "Your descriptive commit message"
   

---

Workflow: Submitting a Pull Request (PR)

When you have completed your changes and verified tests and formatting:

1. Push Branch:

   • For maintainers with write access: Push directly to origin:

     git push origin {branch_name}
     

   • For contributors using a fork: Push to your fork remote:

     git push <fork-remote> {branch_name}
     

2. Create PR using the GitHub CLI (gh):

   • From a direct branch:

     gh pr create --repo firebase/firebase-tools --head {branch_name} --base main --title "Your PR Title" --body "Your PR Description"
     

   • From a fork:

     gh pr create --repo firebase/firebase-tools --head <your-github-username>:{branch_name} --base main --title "Your PR Title" --body "Your PR Description"
     

   Note: If the gh pr create command prompts for interactive input, passing arguments like --title and --body makes it non-interactive. You can also add --draft if the PR is a work-in-progress.