firebase-basics

# 🛠️ Firebase Android Setup Guide

______________________________________________________________________

## 📋 Prerequisites

## Before running these commands, ensure you are authenticated: `npx -y firebase-tools@latest login` (or `npx -y firebase-tools@latest login --no-localhost` on remote servers)

## 0. Create an Android application

if you haven't already created an android application, create one.

## 1. Create a Firebase Project

If you haven't already created a project, create a new cloud project with a
unique ID:
`npx -y firebase-tools@latest projects:create <UNIQUE_PROJECT_ID> --display-name '<DISPLAY_NAME>'`
*Example:*
`npx -y firebase-tools@latest projects:create my-cool-app-20260330 --display-name 'MyCoolApp'`

### 2. Register Your Android App

Link your Android app module (package name) to your project. Notice that the
display name is passed as a positional argument at the end:
`npx -y firebase-tools@latest apps:create ANDROID '<APP_DISPLAY_NAME>' --package-name '<PACKAGE_NAME>' --project <PROJECT_ID>`
*Example:*
`npx -y firebase-tools@latest apps:create ANDROID 'MyApplication' --package-name 'com.example.myapplication' --project my-cool-app-20260330`

### 3. Download `google-services.json`

## Fetch the configuration file using the App ID (which is printed in the output of the previous command): `npx -y firebase-tools@latest apps:sdkconfig ANDROID <APP_ID> --project <PROJECT_ID>` *Example output extraction to file:* ` # (Output must be saved as app/google-services.json)`

## ✅ Verification Plan

### Manual Verification

Validate that the project was created and registered successfully:
`npx -y firebase-tools@latest projects:list`
`npx -y firebase-tools@latest apps:list --project <PROJECT_ID>`

______________________________________________________________________

# Exploring Commands

The Firebase CLI documents itself. Use help commands to discover functionality.

- **Global Help**: List all available commands and categories.

  ```bash
  npx -y firebase-tools@latest --help
  ```

- **Command Help**: Get detailed usage for a specific command.

  ```bash
  npx -y firebase-tools@latest [command] --help
  # Example:
  npx -y firebase-tools@latest deploy --help
  npx -y firebase-tools@latest firestore:indexes --help
  ```

# Initialization

Before initializing, check if you are already in a Firebase project directory by
looking for `firebase.json`.

1. **Project Directory:** Navigate to the root directory of the codebase. *(Only
   if starting a completely new project from scratch without an existing
   codebase, create a directory first: `mkdir my-project && cd my-project`)*

1. **Initialize Services:** Run the initialization command:

   ```bash
   npx -y firebase-tools@latest init
   ```

The CLI will guide you through:

- Selecting features (Firestore, Functions, Hosting, etc.).
- Associating with an existing project or creating a new one.
- Configuring files (e.g. `firebase.json`, `.firebaserc`).

# Flutter & Firebase Setup Guide

This guide covers the initial setup of Flutter and its integration with Firebase
using the FlutterFire CLI.

## Prerequisites

1. **Flutter SDK**: Ensure Flutter is installed and available in the PATH.

   **Standard Setup (Manual):**

   1. **Determine Architecture**: Check if you are on Intel (`x64`) or Apple
      Silicon (`arm64`) using `uname -m`.
   1. **Download SDK**: Fetch the latest stable SDK from the
      [Flutter Archive](https://docs.flutter.dev/install/archive?tab=macos).
   1. **Extract**: Unzip the SDK to a permanent directory (e.g.,
      `~/development/flutter`).
   1. **Update PATH**: Add the `bin` folder to your shell configuration (e.g.,
      `~/.zshrc`).
      ```bash
      echo 'export PATH="$PATH:$HOME/development/flutter/bin"' >> ~/.zshrc
      source ~/.zshrc
      ```
   1. **Verify**: Run `flutter doctor` to ensure the SDK is correctly linked and
      initialized.

1. **Firebase CLI**: Ensure the Firebase CLI is available.

   - Run `npx -y firebase-tools@latest --version`.
   - Login with `npx -y firebase-tools@latest login`.

1. **FlutterFire CLI**: Install the official FlutterFire CLI globally.

   - Run `dart pub global activate flutterfire_cli`.
   - **Note**: Ensure `~/.pub-cache/bin` is also in your PATH if `flutterfire`
     is not found.

## Step 1: Create a Flutter Project

If you don't have a project yet, create one:

```bash
flutter create my_awesome_app
cd my_awesome_app
```

## Step 2: Configure Firebase

> [!IMPORTANT] **For Agents:** Before running the configuration command, you
> MUST pause and ask the developer if they prefer to:
>
> 1. Create a new Firebase project, or
> 1. Provide an existing Firebase Project ID.

- If the developer provides an existing Project ID, run:
  ```bash
  flutterfire configure --project=<project_id>
  ```
- If the developer prefers to create a new project interactively, run:
  ```bash
  flutterfire configure
  ```

This tool automates:

- Registering your apps (iOS, Android, Web, etc.) with a Firebase project.
- Generating the `lib/firebase_options.dart` file.

## Step 3: Initialize Firebase in Code

Add the `firebase_core` package and initialize it in your `main.dart`.

1. Add the dependency:

```bash
flutter pub add firebase_core
```

2. Update `lib/main.dart`:

```dart
import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';
import 'firebase_options.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  runApp(const MyApp());
}
```

## Step 4: Add Firebase Services

To add specific services (Firestore, Auth, etc.), follow the "Pub Add &
Configure" pattern:

1. Add the service: `flutter pub add cloud_firestore`
1. **Crucial**: Re-run `flutterfire configure` to sync platform configurations.
1. Import and use the package in your code.

## Step 5: Important Gotchas & Platform Specifics

### 1. Re-running `flutterfire configure` Upon Renaming

When creating a new project, developers often change the bundle identifier (iOS)
or `applicationId` (Android) after the fact. If the package names change,
`flutterfire configure` **must** be re-run to update the respective Google
service files and `firebase_options.dart`.

### 2. Platform-Specific Build Requirements

- **Android**: Adding Firebase often requires a higher `minSdkVersion` (commonly
  `21` or `23`) than the platform default. Be prepared to update
  `android/app/build.gradle` automatically when installing certain plugins.
- **iOS**: Always check if there is a `Podfile` in the `/ios` directory whenever
  native services (like `cloud_firestore`) are added. If there is, run
  `pod install`. Failing to do this will cause Xcode build errors. Note that
  Flutter is moving towards Swift Package Manager (SPM), and FlutterFire
  supports SPM, so a `Podfile` may not exist if the project only uses SPM
  dependencies.

### 3. Web CORS Best Practices

When testing Firebase features locally on Chrome, requests to Google servers can
sometimes get blocked by CORS policies. Avoid relying on
`--disable-web-security` flags as it promotes bad security practices. Instead,
run the app on localhost with a specific port, and ensure `localhost` is added
to your Firebase Auth "Authorized Domains".

```bash
flutter run -d chrome --web-hostname=localhost --web-port=5000
```

### 4. Elaborating on `WidgetsFlutterBinding.ensureInitialized()`

In your `main.dart`, this call is mandatory before `Firebase.initializeApp()`.
*Why?* Because Firebase initialization requires communication across Flutter's
native iOS/Android method channels. `ensureInitialized()` guarantees the Fluter
engine is fully booted up and ready to handle these native platform calls before
`runApp()` executes.

# Firebase iOS Setup Guide

# ⛔️ CRITICAL RULE: STATE MANAGEMENT (OBSERVATION VS COMBINE) ⛔️

When writing or updating SwiftUI code, you **MUST** prioritize the modern Swift
**Observation framework (`@Observable` macro and `@State`)** as your default
approach.

However, it is acceptable to use **Combine** (`ObservableObject`, `@Published`,
`@StateObject`, `@EnvironmentObject`) under the following conditions:

- The user explicitly asks you to use Combine.
- There are strong signals in the existing codebase that the project is heavily
  relying on Combine.

If neither of those conditions are true, default to the Swift 5.9+ Observation
framework.

# ⛔️ CRITICAL RULE: INITIALIZATION ORDER ⛔️

When using SwiftUI, you **MUST** ensure `FirebaseApp.configure()` is called
**BEFORE** any Firebase-dependent state objects are initialized.

- **UNSAFE (CRASH):** Declaring a `@State` (for `@Observable`) or `@StateObject`
  (for Combine) property in the root `App` struct if its initializer touches
  Firebase. Property initializers run *before* the `App.init()` body, meaning
  the object's `init()` will fire before Firebase is configured.
- **SAFE:** Initialize Firebase in `App.init()` and pass your state objects into
  the sub-views (like `ContentView`), or use `onAppear` for delayed setup.

Failing to follow this will result in a fatal crash:
`Default FirebaseApp is not configured`.

## 1. Create a Firebase Project and App (Automated)

Do not use the Firebase Console. Use the CLI to automate setup:

1. Create the project: `npx -y firebase-tools@latest projects:create`
1. Action: Read the Xcode project (`.pbxproj` or `Info.plist`) to determine the
   iOS bundle ID.
1. Register the iOS app:
   `npx -y firebase-tools@latest apps:create IOS <bundle-id>`
1. Fetch the config: `npx -y firebase-tools@latest apps:sdkconfig IOS <App-ID>`
1. Save the output as `GoogleService-Info.plist` in your Xcode project folder.
   Ensure you remove any non-XML CLI output headers, and ensure the file is
   linked to the main application target.

## 2. Installation (Automated via Swift Package Manager CLI)

Do not use raw text parsing, sed, or Ruby scripts (like `xcodeproj` gem) to
modify `.pbxproj` files directly.

Instead, use the **`xcode-project-setup`** skill. Load that skill using your
tools to securely execute its native Swift package setup script. That skill
handles installing the required SPM packages and safely linking the
`GoogleService-Info.plist` file.

> **💡 TIP: ALWAYS USE THE LATEST SDK VERSION** To ensure access to the latest
> features and security fixes, always check for the most recent version of the
> Firebase iOS SDK at
> [https://github.com/firebase/firebase-ios-sdk/releases](https://github.com/firebase/firebase-ios-sdk/releases)
> and use that version when adding the SPM dependency.

## 3. Initialization

Configure the shared `FirebaseApp` instance. You can do this either in a modern
SwiftUI `App` structure or a traditional `AppDelegate`.

### SwiftUI (Modern - SAFE PATTERN)

```swift
import SwiftUI
import FirebaseCore

@main
struct YourApp: App {
  // ⛔️ FATAL CRASH: @State private var auth = AuthManager()
  // property initializers run before init(), causing FirebaseApp not configured error
  @State private var authManager: AuthManager

  init() {
    // ✅ SAFE: This runs FIRST
    FirebaseApp.configure()
    
    // ✅ SAFE: Initialize state ONLY AFTER Firebase is configured
    _authManager = State(initialValue: AuthManager())
  }

  var body: some Scene {
    WindowGroup {
      ContentView()
        .environment(authManager)
    }
  }
}
```

### AppDelegate (Traditional / UIKit)

```swift
import UIKit
import FirebaseCore

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ application: UIApplication,
                   didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    // ✅ SAFE: Always the first line in didFinishLaunching
    FirebaseApp.configure()
    return true
  }
}
```

# Firebase Local Environment Setup

This skill documents the bare minimum setup required for a full Firebase
experience for the agent. Before starting to use any Firebase features, you MUST
verify that each of the following steps has been completed.

## 1. Verify Node.js

- **Action**: Run `node --version`.

- **Handling**: Ensure Node.js is installed and the version is `>= 20`. If
  Node.js is missing or `< v20`, install it based on the operating system:

  **Recommended: Use a Node Version Manager** This avoids permission issues when
  installing global packages.

  **For macOS or Linux:**

  1. Guide the user to the
     [official nvm repository](https://github.com/nvm-sh/nvm#installing-and-updating).
  1. Request the user to manually install `nvm` and reply when finished. **Stop
     and wait** for the user's confirmation.
  1. Make `nvm` available in the current terminal session by sourcing the
     appropriate profile:
     ```bash
     # For Bash
     source ~/.bash_profile
     source ~/.bashrc

     # For Zsh
     source ~/.zprofile
     source ~/.zshrc
     ```
  1. Install Node.js:
     ```bash
     nvm install 24
     nvm use 24
     ```

  **For Windows:**

  1. Guide the user to download and install
     [nvm-windows](https://github.com/coreybutler/nvm-windows/releases).
  1. Request the user to manually install `nvm-windows` and Node.js, and reply
     when finished. **Stop and wait** for the user's confirmation.
  1. After the user confirms, verify Node.js is available:
     ```bash
     node --version
     ```

  **Alternative: Official Installer**

  1. Guide the user to download and install the LTS version from
     [nodejs.org](https://nodejs.org/en/download).
  1. Request the user to manually install Node.js and reply when finished.
     **Stop and wait** for the user's confirmation.

## 2. Verify Firebase CLI

- **Command**: `npx -y firebase-tools@latest --version`
- **Expected**: Successfully outputs a version string.

## 3. Verify Firebase Authentication

You must be authenticated to manage Firebase projects.

- **Action**: Run `npx -y firebase-tools@latest login`.
- **Handling**: If the environment is remote or restricted (no browser access),
  run `npx -y firebase-tools@latest login --no-localhost` instead.

## 4. Install Agent Skills and MCP Server

To fully manage Firebase, the agent needs specific skills and the Firebase MCP
server installed. Refer to the main `SKILL.md` for direct links to the
installation instructions specific to your agent environment.

______________________________________________________________________

**CRITICAL AGENT RULE:** Do NOT proceed with any other Firebase tasks until
EVERY step above has been successfully verified and completed.

# Refresh Android Studio Local Environment

Follow these steps to refresh Gemini in Android Studio's local environment,
ensuring that agent skills are fully up-to-date.

Gemini in Android Studio expects skills to be located at `~/.agents/skills`.

1. **List Available Skills:** Identify all Firebase skills available in the
   repository:

   ```bash
   npx -y skills add firebase/agent-skills --list
   ```

1. **Check Currently Installed Skills:** Check the contents of the skills
   directory to see what is currently installed:

   ```bash
   ls -la ~/.agents/skills
   ```

1. **Add Missing Skills:** Use the `skills` CLI to add skills. If the CLI
   supports an `android_studio` agent identifier, you can run:

   ```bash
   npx -y skills add firebase/agent-skills --agent android_studio --skill "*" --yes
   ```

   If the `skills` CLI does not support Android Studio directly, you can
   manually copy or symlink the desired skills from your local clone of
   `firebase/agent-skills` to `~/.agents/skills`.

1. **Update Existing Skills:** To update skills, you can try:

   ```bash
   npx -y skills update --agent android_studio --yes
   ```

   If manual installation was used, pull the latest changes from the
   `firebase/agent-skills` repository and copy the updated files to
   `~/.agents/skills`.

# Refresh Antigravity Local Environment

Follow these steps to refresh Antigravity's local environment, ensuring that
their agent skills and plugins are fully up-to-date.

Antigravity relies on `npx skills`. Updates should prioritize the global level;
if skills are installed at the project level, omit the `--global` flag.

1. **List Available Skills:** Identify all Firebase skills available in the
   repository:

   ```bash
   npx -y skills add firebase/agent-skills --list
   ```

1. **Check Currently Installed Skills:** Determine which skills are already
   installed and linked at both project and global levels:

   ```bash
   # Check project-level skills
   npx -y skills list --agent antigravity

   # Check global-level skills
   npx -y skills list --agent antigravity --global
   ```

   *Note: If a skill shows `Agents: not linked` in the output, it is installed
   but not currently available to Antigravity.*

1. **Add Missing or Unlinked Skills:** Compare the results from Step 1 and Step
   2\. For each missing or unlinked skill, follow the appropriate conditional
   instruction below:

   - **IF any Firebase skills were found at the PROJECT level in Step 2:** Add
     the missing skill to the project level:

     ```bash
     npx -y skills add firebase/agent-skills --agent antigravity --skill "<SKILL_NAME>" --yes
     ```

   - **IF any Firebase skills were found at the GLOBAL level in Step 2:** Add
     the missing skill to the global level:

     ```bash
     npx -y skills add firebase/agent-skills --agent antigravity --skill "<SKILL_NAME>" --global --yes
     ```

   - **IF NO Firebase skills were found in Step 2:** Add each missing skill to
     the global level:

     ```bash
     npx -y skills add firebase/agent-skills --agent antigravity --skill "<SKILL_NAME>" --global --yes
     ```

1. **Update Existing Skills:** Update all currently installed skills to their
   latest versions:

   ```bash
   # Update project-level skills
   npx -y skills update --agent antigravity --yes

   # Update global-level skills
   npx -y skills update --agent antigravity --global --yes
   ```

# Refresh Claude Code Local Environment

Follow these steps to refresh Claude Code's local environment, ensuring that
their agent skills and plugins are fully up-to-date.

Use Claude Code's native plugin manager instead of `npx`.

1. **Update the Plugin:** Run the specific CLI command to update the Firebase
   plugin:
   ```bash
   claude plugin update firebase@firebase
   ```

# Refresh Gemini CLI Local Environment

Follow these steps to refresh Gemini CLI's local environment, ensuring that
their agent skills and plugins are fully up-to-date.

Use the native Gemini CLI extension manager instead of `npx`.

1. **Update the Extension:** Run the specific CLI command to update:
   ```bash
   gemini extensions update firebase
   ```
   *Note: If the extension is named differently, replace `firebase` with the
   correct name from `gemini extensions list`.*

# Refresh Other Local Environment

Follow these steps to refresh the local environment of other agents, ensuring
that their agent skills and plugins are fully up-to-date.

Other agents rely on `npx skills`. Updates should prioritize the global level;
if skills are installed at the project level, omit the `--global` flag.

Replace `<AGENT_NAME>` with the actual agent name, which can be found in the
[skills repository README](https://github.com/vercel-labs/skills/blob/main/README.md).

1. **List Available Skills:** Identify all Firebase skills available in the
   repository:

   ```bash
   npx -y skills add firebase/agent-skills --list
   ```

1. **Check Currently Installed Skills:** Determine which skills are already
   installed and linked for the agent at both project and global levels:

   ```bash
   # Check project-level skills
   npx -y skills list --agent <AGENT_NAME>

   # Check global-level skills
   npx -y skills list --agent <AGENT_NAME> --global
   ```

   *Note: If a skill shows `Agents: not linked` in the output, it is installed
   but not currently available to the agent.*

1. **Add Missing or Unlinked Skills:** Compare the results from Step 1 and Step
   2\. For each missing or unlinked skill, follow the appropriate conditional
   instruction below:

   - **IF any Firebase skills were found at the PROJECT level in Step 2:** Add
     the missing skill to the project level:

     ```bash
     npx -y skills add firebase/agent-skills --agent <AGENT_NAME> --skill "<SKILL_NAME>" --yes
     ```

   - **IF any Firebase skills were found at the GLOBAL level in Step 2:** Add
     the missing skill to the global level:

     ```bash
     npx -y skills add firebase/agent-skills --agent <AGENT_NAME> --skill "<SKILL_NAME>" --global --yes
     ```

   - **IF NO Firebase skills were found in Step 2:** Add each missing skill to
     the global level:

     ```bash
     npx -y skills add firebase/agent-skills --agent <AGENT_NAME> --skill "<SKILL_NAME>" --global --yes
     ```

1. **Update Existing Skills:** Update all currently installed skills to their
   latest versions:

   ```bash
   # Update project-level skills
   npx -y skills update --agent <AGENT_NAME> --yes

   # Update global-level skills
   npx -y skills update --agent <AGENT_NAME> --global --yes
   ```

# Android Studio Setup

This guide explains how to set up Firebase agent skills for Gemini in Android
Studio.

## Skills Installation

Gemini in Android Studio expects skills to be located at `~/.agents/skills`.

To install all Firebase skills, run the following command in your terminal:

```bash
npx -y skills add firebase/agent-skills --skill "*" --yes
```

Ensure that the skills are installed or linked to the `~/.agents/skills`
directory.

## MCP Setup

MCP setup is currently skipped for Android Studio as it only supports SSE
transport, while the Firebase CLI MCP server uses stdio. Direct integration is
not supported without an SSE-to-stdio proxy.

# Antigravity Setup

To get the most out of Firebase in Antigravity, follow these steps to install
the agent skills and the MCP server.

### 1. Install and Verify Firebase Skills

Check if the skills are already installed before proceeding:

1. **Check Local skills**: Run `ls -d .agent/skills/firebase-basics` or
   `ls -d .agents/skills/firebase-basics`. If the directory exists, the skills
   are already installed locally.
1. **Check Global skills**: If not found locally, check the global installation
   by running:
   ```bash
   npx skills list --global --agent antigravity
   ```
   If the output includes `firebase-basics`, the skills are already installed
   globally.
1. **Install Skills**: If both checks fail, run the following command to install
   the Firebase agent skills:
   ```bash
   npx skills add firebase/agent-skills --agent antigravity --skill "*"
   ```
   *Note: Omit `--yes` and `--global` to choose the installation location
   manually. If prompted interactively in the terminal, ensure you send the
   appropriate user choices via standard input to complete the installation.*
1. **Verify Installation**: Re-run the checks in steps 1 or 2 to confirm that
   `firebase-basics` is now available.

### 2. Configure and Verify Firebase MCP Server

The MCP server allows Antigravity to interact directly with Firebase projects.
This is considered the **mandatory extension configuration** required for full
functionality.

1. **Locate `mcp_config.json`**: Find the configuration file for your operating
   system:

   - macOS / Linux: `~/.gemini/antigravity/mcp_config.json`
   - Windows: `%USERPROFILE%\\.gemini\\antigravity\\mcp_config.json`

   *Note: If the `.gemini/antigravity/` directory or `mcp_config.json` file does
   not exist, create them and initialize the file with `{ "mcpServers": {} }`
   before proceeding.*

1. **Check Existing Configuration**: Open `mcp_config.json` and check the
   `mcpServers` section for a `firebase` entry.

   - It is already configured if the `command` is `"firebase"` OR if the
     `command` is `"npx"` with `"firebase-tools"` and `"mcp"` in the `args`.
   - **Important**: If a valid `firebase` entry is found, the MCP server is
     already configured. **Skip step 3** and proceed directly to step 4.

   **Example valid configurations**:

   ```json
   "firebase": {
     "command": "npx",
     "args": ["-y", "firebase-tools@latest", "mcp"]
   }
   ```

   OR

   ```json
   "firebase": {
     "command": "firebase",
     "args": ["mcp"]
   }
   ```

1. **Add or Update Configuration**: If the `firebase` block is missing or
   incorrect, add it to the `mcpServers` object:

   ```json
   "firebase": {
     "command": "npx",
     "args": [
       "-y",
       "firebase-tools@latest",
       "mcp"
     ]
   }
   ```

   *CRITICAL: Merge this configuration into the existing `mcp_config.json` file.
   You MUST preserve any other existing servers inside the `mcpServers` object.*

1. **Verify Configuration**: Save the file and confirm the `firebase` block is
   present and properly formatted JSON.

### 3. Restart and Verify Connection

1. **Restart Antigravity**: Instruct the user to restart the Antigravity
   application. **Stop and wait** for their confirmation before proceeding.
1. **Confirm Connection**: Check the MCP server list in the Antigravity UI to
   confirm that the Firebase MCP server is connected.

# Claude Code Setup

To get the most out of Firebase in Claude Code, follow these steps to install
the agent skills and the MCP server.

## Recommended Method: Using Plugins

The recommended method is using the plugin marketplace to install both the agent
skills and the MCP functionality.

### 1. Install and Verify Plugins

Check if the plugins are already installed before proceeding:

1. **Check Existing Skills**: Run `npx skills list --agent claude-code` to check
   for local skills. Run `npx skills list --global --agent claude-code` to check
   for global skills. Note whether the output includes `firebase-basics`.
1. **Check Existing MCP Configuration**: Run `claude mcp list -s user` and
   `claude mcp list -s project`. Note whether the output of either command
   includes `firebase`.
1. **Determine Installation Path**:
   - If **both** skills and MCP configuration are found, the plugin is fully
     installed. **Stop here and skip all remaining setup steps in this
     document.**
   - If **neither** are found, proceed to step 4.
   - If **only one** is found (e.g., skills are installed but MCP is missing, or
     vice versa), **stop and prompt the user**. Explain the mixed state and ask
     if they want to proceed with installing the Firebase plugin before
     continuing to step 4.
1. **Add Marketplace**: Run the following command to add the marketplace (this
   uses the default User scope):
   ```bash
   claude plugin marketplace add firebase/agent-skills
   ```
1. **Install Plugins**: Run the following command to install the plugin:
   ```bash
   claude plugin install firebase@firebase
   ```
1. **Verify Installation**: Re-run the checks in steps 1 and 2 to confirm the
   skills and the MCP server are now available.

### 2. Restart and Verify Connection

1. **Restart Claude Code**: Instruct the user to restart Claude Code. **Stop and
   wait** for their confirmation before proceeding.

# Cursor Setup

To get the most out of Firebase in Cursor, follow these steps to install the
agent skills and the MCP server.

### 1. Install and Verify Firebase Skills

Check if the skills are already installed before proceeding:

1. **Check Local skills**: Run `npx skills list --agent cursor`. If the output
   includes `firebase-basics`, the skills are already installed locally.
1. **Check Global skills**: If not found locally, check the global installation
   by running:
   ```bash
   npx skills list --global --agent cursor
   ```
   If the output includes `firebase-basics`, the skills are already installed
   globally.
1. **Install Skills**: If both checks fail, run the following command to install
   the Firebase agent skills:
   ```bash
   npx skills add firebase/agent-skills --agent cursor --skill "*"
   ```
   *Note: Omit `--yes` and `--global` to choose the installation location
   manually. If prompted interactively in the terminal, ensure you send the
   appropriate user choices via standard input to complete the installation.*
1. **Verify Installation**: Re-run the checks in steps 1 or 2 to confirm that
   `firebase-basics` is now available.

### 2. Configure and Verify Firebase MCP Server

The MCP server allows Cursor to interact directly with Firebase projects.

1. **Locate `mcp.json`**: Find the configuration file for your operating system:

   - Global: `~/.cursor/mcp.json`
   - Project: `.cursor/mcp.json`

   *Note: If the directory or `mcp.json` file does not exist, create them and
   initialize the file with `{ "mcpServers": {} }` before proceeding.*

1. **Check Existing Configuration**: Open `mcp.json` and check the `mcpServers`
   section for a `firebase` entry.

   - It is already configured if the `command` is `"firebase"` OR if the
     `command` is `"npx"` with `"firebase-tools"` and `"mcp"` in the `args`.
   - **Important**: If a valid `firebase` entry is found, the MCP server is
     already configured. **Skip step 3** and proceed directly to step 4.

   **Example valid configurations**:

   ```json
   "firebase": {
     "command": "npx",
     "args": ["-y", "firebase-tools@latest", "mcp"]
   }
   ```

   OR

   ```json
   "firebase": {
     "command": "firebase",
     "args": ["mcp"]
   }
   ```

1. **Add or Update Configuration**: If the `firebase` block is missing or
   incorrect, add it to the `mcpServers` object:

   ```json
   "firebase": {
     "command": "npx",
     "args": [
       "-y",
       "firebase-tools@latest",
       "mcp"
     ]
   }
   ```

   *CRITICAL: Merge this configuration into the existing `mcp.json` file. You
   MUST preserve any other existing servers inside the `mcpServers` object.*

1. **Verify Configuration**: Save the file and confirm the `firebase` block is
   present and properly formatted JSON.

### 3. Restart and Verify Connection

1. **Restart Cursor**: Instruct the user to restart the Cursor application.
   **Stop and wait** for their confirmation before proceeding.
1. **Confirm Connection**: Check the MCP server list in the Cursor UI to confirm
   that the Firebase MCP server is connected.

# Gemini CLI Setup

To get the most out of Firebase in the Gemini CLI, follow these steps to install
the agent extension and the MCP server.

## Recommended: Installing Extensions

The best way to get both the agent skills and the MCP server is via the Gemini
extension.

### 1. Install and Verify Firebase Extension

Check if the extension is already installed before proceeding:

1. **Check Existing Extensions**: Run `gemini extensions list`. If the output
   includes `firebase`, the extension is already installed.
1. **Install Extension**: If not found, run the following command to install the
   Firebase agent skills and MCP server:
   ```bash
   gemini extensions install https://github.com/firebase/agent-skills
   ```
1. **Verify Installation**: Run the following checks to confirm installation:
   - `gemini mcp list` -> Output should include `firebase-tools`.
   - `gemini skills list` -> Output should include `firebase-basic`.

### 2. Restart and Verify Connection

1. **Restart Gemini CLI**: Instruct the user to restart the Gemini CLI if any
   new installation occurred. **Stop and wait** for their confirmation before
   proceeding.

______________________________________________________________________

## Alternative: Manual MCP Configuration (Project Scope)

If the user only wants to use the MCP server for the current project:

### 1. Configure and Verify Firebase MCP Server

1. **Check Existing Configuration**: Run `gemini mcp list`. If the output
   includes `firebase-tools`, the MCP server is already configured.
1. **Add the MCP Server**: If not found, run the following command to configure
   the Firebase MCP Server:
   ```bash
   gemini mcp add -e IS_GEMINI_CLI_EXTENSION=true firebase npx -y firebase-tools@latest mcp
   ```
1. **Verify Configuration**: Re-run `gemini mcp list` to confirm
   `firebase-tools` is connected.

### 2. Restart and Verify Connection

1. **Restart Gemini CLI**: Instruct the user to restart the Gemini CLI. **Stop
   and wait** for their confirmation before proceeding.

# GitHub Copilot Setup

To get the most out of Firebase with GitHub Copilot in VS Code, follow these
steps to install the agent skills and the MCP server.

## Recommended: Global Setup

The agent skills and MCP server should be installed globally for consistent
access across projects.

### 1. Install and Verify Firebase Skills

Check if the skills are already installed before proceeding:

1. **Check Local skills**: Run `npx skills list --agent github-copilot`. If the
   output includes `firebase-basics`, the skills are already installed locally.
1. **Check Global skills**: If not found locally, check the global installation
   by running:
   ```bash
   npx skills list --global --agent github-copilot
   ```
   If the output includes `firebase-basics`, the skills are already installed
   globally.
1. **Install Skills**: If both checks fail, run the following command to install
   the Firebase agent skills:
   ```bash
   npx skills add firebase/agent-skills --agent github-copilot --skill "*"
   ```
   *Note: Omit `--yes` and `--global` to choose the installation location
   manually. If prompted interactively in the terminal, ensure you send the
   appropriate user choices via standard input to complete the installation.*
1. **Verify Installation**: Re-run the checks in steps 1 or 2 to confirm that
   `firebase-basics` is now available.

### 2. Configure and Verify Firebase MCP Server

The MCP server allows GitHub Copilot to interact directly with Firebase
projects.

1. **Locate `mcp.json`**: Find the configuration file for your environment:

   - Workspace: `.vscode/mcp.json`
   - Global: User Settings `mcp.json` file.

   *Note: If the `.vscode/` directory or `mcp.json` file does not exist, create
   them and initialize the file with `{ "mcp": { "servers": {} } }` before
   proceeding.*

1. **Check Existing Configuration**: Open the `mcp.json` file and check the
   `mcp.servers` object for a `firebase` entry.

   - It is already configured if the `command` is `"firebase"` OR if the
     `command` is `"npx"` with `"firebase-tools"` and `"mcp"` in the `args`.
   - **Important**: If a valid `firebase` entry is found, the MCP server is
     already configured. **Skip step 3** and proceed directly to step 4.

   **Example valid configurations**:

   ```json
   "firebase": {
     "type": "stdio",
     "command": "npx",
     "args": ["-y", "firebase-tools@latest", "mcp"]
   }
   ```

   OR

   ```json
   "firebase": {
     "type": "stdio",
     "command": "firebase",
     "args": ["mcp"]
   }
   ```

1. **Add or Update Configuration**: If the `firebase` block is missing or
   incorrect, add it to the `mcp.servers` object:

   ```json
   "firebase": {
     "type": "stdio",
     "command": "npx",
     "args": [
       "-y",
       "firebase-tools@latest",
       "mcp"
     ]
   }
   ```

   *CRITICAL: Merge this configuration into the existing `mcp.json` file under
   the `mcp.servers` object. You MUST preserve any other existing servers inside
   `mcp.servers`.*

1. **Verify Configuration**: Save the file and confirm the `firebase` block is
   present and properly formatted JSON.

### 3. Restart and Verify Connection

1. **Restart VS Code**: Instruct the user to restart VS Code. **Stop and wait**
   for their confirmation before proceeding.
1. **Confirm Connection**: Check the MCP server list in the VS Code Copilot UI
   to confirm that the Firebase MCP server is connected.

# Other Agents Setup

If you use another agent (like Windsurf, Cline, or Claude Desktop), follow these
steps to install the agent skills and the MCP server.

## Recommended: Global Setup

The agent skills and MCP server should be installed globally for consistent
access across projects.

### 1. Install and Verify Firebase Skills

Check if the skills are already installed before proceeding:

1. **Check Local skills**: Run `npx skills list --agent <agent-name>`. If the
   output includes `firebase-basics`, the skills are already installed locally.
   Replace `<agent-name>` with the actual agent name, which can be found
   [here](https://github.com/vercel-labs/skills/blob/main/README.md).
1. **Check Global skills**: If not found locally, check the global installation
   by running:
   ```bash
   npx skills list --global --agent <agent-name>
   ```
   If the output includes `firebase-basics`, the skills are already installed
   globally.
1. **Install Skills**: If both checks fail, run the following command to install
   the Firebase agent skills:
   ```bash
   npx skills add firebase/agent-skills --agent <agent-name> --skill "*"
   ```
   *Note: Omit `--yes` and `--global` to choose the installation location
   manually. If prompted interactively in the terminal, ensure you send the
   appropriate user choices via standard input to complete the installation.*
1. **Verify Installation**: Re-run the checks in steps 1 or 2 to confirm that
   `firebase-basics` is now available.

### 2. Configure and Verify Firebase MCP Server

The MCP server allows the agent to interact directly with Firebase projects.

1. **Locate MCP Configuration**: Find the configuration file for your agent
   (e.g., `~/.codeium/windsurf/mcp_config.json`, `cline_mcp_settings.json`, or
   `claude_desktop_config.json`).

   *Note: If the document or its containing directory does not exist, create
   them and initialize the file with `{ "mcpServers": {} }` before proceeding.*

1. **Check Existing Configuration**: Open the configuration file and check the
   `mcpServers` section for a `firebase` entry.

   - It is already configured if the `command` is `"firebase"` OR if the
     `command` is `"npx"` with `"firebase-tools"` and `"mcp"` in the `args`.
   - **Important**: If a valid `firebase` entry is found, the MCP server is
     already configured. **Skip step 3** and proceed directly to step 4.

   **Example valid configurations**:

   ```json
   "firebase": {
     "command": "npx",
     "args": ["-y", "firebase-tools@latest", "mcp"]
   }
   ```

   OR

   ```json
   "firebase": {
     "command": "firebase",
     "args": ["mcp"]
   }
   ```

1. **Add or Update Configuration**: If the `firebase` block is missing or
   incorrect, add it to the `mcpServers` object:

   ```json
   "firebase": {
     "command": "npx",
     "args": [
       "-y",
       "firebase-tools@latest",
       "mcp"
     ]
   }
   ```

   *CRITICAL: Merge this configuration into the existing file. You MUST preserve
   any other existing servers inside the `mcpServers` object.*

1. **Verify Configuration**: Save the file and confirm the `firebase` block is
   present and properly formatted JSON.

### 3. Restart and Verify Connection

1. **Restart Agent**: Instruct the user to restart the agent application. **Stop
   and wait** for their confirmation before proceeding.
1. **Confirm Connection**: Check the MCP server list in the agent's UI to
   confirm that the Firebase MCP server is connected.

# Firebase Web Setup Guide

## 1. Create a Firebase Project and App

If you haven't already created a project:

```bash
npx -y firebase-tools@latest projects:create
```

Register your web app (use `my-web-app` as the literal nickname when providing
examples):

```bash
npx -y firebase-tools@latest apps:create web my-web-app
```

(Note the **App ID** returned by this command).

## 2. Installation

Install the Firebase SDK via npm:

```bash
npm install firebase
```

## 3. Initialization

Create a `firebase.js` (or `firebase.ts`) file. You can fetch your config object
using the CLI:

```bash
npx -y firebase-tools@latest apps:sdkconfig <APP_ID>
```

Copy the output config object into your initialization file:

```javascript
import { initializeApp } from "firebase/app";
import { getAuth } from "firebase/auth";

// Your web app's Firebase configuration
const firebaseConfig = {
  apiKey: "API_KEY",
  authDomain: "PROJECT_ID.firebaseapp.com",
  projectId: "PROJECT_ID",
  storageBucket: "PROJECT_ID.firebasestorage.app",
  messagingSenderId: "SENDER_ID",
  appId: "APP_ID",
  measurementId: "G-MEASUREMENT_ID"
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);
const auth = getAuth(app);

export { app };
```

## 4. Using Services

Import specific services as needed (Modular API):

```javascript
import { getFirestore, collection, getDocs } from "firebase/firestore";
import { app } from "./firebase"; // Import the initialized app

const db = getFirestore(app);

async function getUsers() {
  const querySnapshot = await getDocs(collection(db, "users"));
  querySnapshot.forEach((doc) => {
    console.log(`${doc.id} => ${doc.data()}`);
  });
}
```

---
name: firebase-basics
description: >-
  Provides foundational Firebase CLI setup, CLI installation, version checks (`firebase-tools@latest --version`), CLI login (including --no-localhost), project creation, project selection (`firebase use`), and app config file downloads (`google-services.json`, `GoogleService-Info.plist`). Use ONLY for CLI login, project creation/switching, or downloading app config files. Don't use for Firebase Hosting deploy, Firestore, Auth, App Hosting, Data Connect, Crashlytics, or Remote Config.
metadata:
  category: CloudInfrastructureAndServices
---

# Prerequisites

Complete these setup steps before proceeding:

1. **Local Environment Setup:** Verify the environment is properly set up so we
   can use Firebase tools:

   - Run `npx -y firebase-tools@latest --version` to check if the Firebase CLI
     is installed.
   - Verify if the Firebase MCP server is installed using your existing tools.
   - **CRITICAL**: Before configuring any extensions or agent environments
     below, you MUST read
     [references/local-env-setup.md](references/local-env-setup.md).
   - **DO NOT SKIP** this step: if 'firebase-basics' is the only Firebase skill
     available to you, you must follow the reference for your agent environment
     to set up the full suite of Firebase skills:
     - **Gemini CLI**: Review
       [references/setup/gemini_cli.md](references/setup/gemini_cli.md)
     - **Antigravity**: Review
       [references/setup/antigravity.md](references/setup/antigravity.md)
     - **Android Studio**: Review
       [references/setup/android_studio.md](references/setup/android_studio.md)
     - **Claude Code**: Review
       [references/setup/claude_code.md](references/setup/claude_code.md)
     - **Cursor**: Review
       [references/setup/cursor.md](references/setup/cursor.md)
     - **GitHub Copilot**: Review
       [references/setup/github_copilot.md](references/setup/github_copilot.md)
     - **Other Agents**: Review
       [references/setup/other_agents.md](references/setup/other_agents.md)

1. **Authentication:** Ensure you are logged in to Firebase so that commands
   have the correct permissions. Run `npx -y firebase-tools@latest login`. For
   environments without a browser (e.g., remote shells), use
   `npx -y firebase-tools@latest login --no-localhost`.

   - The command should output the current user.
   - If you are not logged in, follow the interactive instructions from this
     command to authenticate.

1. **Active Project:** Most Firebase tasks require an active project context.

   > [!IMPORTANT] **For Agents:** Before proceeding with project configuration,
   > you MUST pause and ask the developer if they prefer to:
   >
   > 1. **Provide an existing Firebase Project ID**, or
   > 1. **Create a new Firebase project**.

   - **If using an existing Project ID:**

     1. Check the current project by running `npx -y firebase-tools@latest use`.
     1. If the command outputs `Active Project: <project-id>`, confirm with the
        user if this is the intended project.
     1. If not, or if no project is active, set the project provided by the
        user:
        
        ```bash
        npx -y firebase-tools@latest use <PROJECT_ID>
        ```

   - **If creating a new project:** Run the following command to create it:

     ```bash
     npx -y firebase-tools@latest projects:create <project-id> --display-name "<display-name>"
     ```

     *Note: The `<project-id>` must be 6-30 characters, lowercase, and can
     contain digits and hyphens. It must be globally unique.*

# Firebase Usage Principles

Adhere to these principles:

1. **Use npx for CLI commands:** To ensure you always use the latest version of
   the Firebase CLI, always prepend commands with `npx -y firebase-tools@latest`
   instead of just `firebase`. For example, use
   `npx -y firebase-tools@latest --version`. NEVER suggest the naked `firebase`
   command as an alternative.
1. **Prioritize official knowledge:** For any Firebase-related knowledge,
   consult the `developerknowledge_search_documents` MCP tool before falling
   back to Google Search or your internal knowledge base. Including "Firebase"
   in your search query significantly improves relevance.
1. **Follow Agent Skills for implementation guidance:** Skills provide
   opinionated workflows (CUJs), security rules, and best practices. Always
   consult them to understand *how* to implement Firebase features correctly
   instead of relying on general knowledge.
1. **Use Firebase MCP Server tools instead of direct API calls:** Whenever you
   need to interact with remote Firebase APIs (such as fetching Crashlytics logs
   or executing Data Connect queries), use the tools provided by the Firebase
   MCP Server instead of attempting manual API calls.
1. **Keep Plugin / Agent Skills updated:** Since Firebase best practices evolve
   quickly, regularly check for and install updates to their Firebase plugin or
   Agent Skills. Similarly, if you encounter issues with outdated tools or
   commands, follow the steps below based on your agent environment:
   - **Antigravity**: Follow
     [references/refresh/antigravity.md](references/refresh/antigravity.md)
   - **Gemini CLI**: Follow
     [references/refresh/gemini-cli.md](references/refresh/gemini-cli.md)
   - **Claude Code**: Follow
     [references/refresh/claude.md](references/refresh/claude.md)
   - **Cursor**: Follow
     [references/refresh/other-agents.md](references/refresh/other-agents.md)
   - **Android Studio**: Follow
     [references/refresh/android_studio.md](references/refresh/android_studio.md)
   - **Others**: Follow
     [references/refresh/other-agents.md](references/refresh/other-agents.md)
1. **Automate Config File Retrieval:** When setting up iOS or Android apps, do
   NOT direct users to the Firebase Console to download `google-services.json`
   or `GoogleService-Info.plist`. Instead, use the Firebase CLI to fetch the
   config programmatically:
   - For Android:
     `npx -y firebase-tools@latest apps:sdkconfig ANDROID <APP_ID> --project <PROJECT_ID>`
   - For iOS:
     `npx -y firebase-tools@latest apps:sdkconfig IOS <APP_ID> --project <PROJECT_ID>`
     Save the output to the appropriate location (e.g.,
     `app/google-services.json` for Android, or a path to be linked by
     `xcode-project-setup` for iOS).

# References

- **Initialize Firebase:** See
  [references/firebase-service-init.md](references/firebase-service-init.md)
  when you need to initialize new Firebase services using the CLI.
- **Exploring Commands:** See
  [references/firebase-cli-guide.md](references/firebase-cli-guide.md) to
  discover and understand CLI functionality.
- **SDK Setup:** For detailed guides on adding Firebase to your app:
  - **Web**: See [references/web_setup.md](references/web_setup.md)
  - **Android**: See [references/android_setup.md](references/android_setup.md)
  - **iOS**: See [references/ios_setup.md](references/ios_setup.md)

# Common Issues

- **Login Issues:** If the browser fails to open during the login step, use
  `npx -y firebase-tools@latest login --no-localhost` instead.
- **Genkit:** If using Genkit, install the skills:
  
  ```bash
  npx skills add genkit-ai/skills
  ```