firebase-tools GEMINI.md

GEMINI.md

This file provides guidance to Gemini CLI or other coding agents when working with code in this repository. It focuses on key conventions and best practices. For a comprehensive guide on the development setup and contribution process, see CONTRIBUTING.md.

Essential Commands

# Build the project
npm run build

# Link the package - once this is run, you can manually test changes in your terminal
npm link

npm test                         # Full test suite with linting and compilation
npm run mocha:fast               # Quick unit tests only
npx mocha {testfile}             # Quick unit test for a specific file

# Linting and formatting
npm run lint                     # Check all code
npm run lint:changed-files       # Lint changed files only (much faster)
npm run format                   # Auto-fix formatting issues

Best Practices

Code Quality & Utilities

• Look for existing utilities first: Before writing common helper functions (e.g., for logging, file system operations, promises, string manipulation), check src/utils.ts to see if a suitable function already exists.
• Use the central logger (src/logger.ts); never use console.log() for user-facing output.
• Throw FirebaseError (src/error.ts) for expected, user-facing errors. If the error is due to a violation of a precondition (e.g. something that is null but should never be), specify a non-zero exit code.
• API calls must use apiv2.ts for authenticated requests.
• Reduce nesting as much as possible: Code should avoid unnecessarily deep nesting or long periods of nesting. Use early returns, continue, and break statements in functions and loops to handle edge cases early and keep main logic flat. Consider helper functions to encapsulate complex branching.

TypeScript

• Never use any or unknown as an escape hatch. Define proper interfaces/types or use type guards.
• Use strict null checks and handle undefined/null explicitly.
• Prefer falsy checks over explicit boolean comparisons: Use !something instead of something === false unless you explicitly need to distinguish between false and other falsy values like undefined or null.