Firebase Provider

Overview

Use this preset to provision an OTA server on Firebase. For a new app, start with Choose infrastructure. Provision the provider resources here, then connect your app with the verified URL and key.

Prerequisites

You need the following resources and access. An AI agent can prepare missing resources through its available provider tools.

• Node.js: The CLI requires 20.19+. Agent setup uses a client-key helper that requires Node 22.18+ or Node 24+; prepare it before provisioning resources.
• Firebase account and project access: Sign in to the account that will own the deployment. An agent can discover an existing project or create a missing one.
• Google Cloud CLI (terminal setup): Install gcloud and authenticate the account that owns the Firebase project.
• Service readiness: Agent setup can enable Storage and prepare Firestore. Terminal init needs Storage enabled so it can find the project's canonical default .firebasestorage.app or .appspot.com bucket. Complete any required billing activation in your account when prompted.

Step 1: Install required packages

Complete Install packages in the React Native project before running init or an agent scaffold. Install the CLI, React Native SDK, and the build adapter that matches your app, then install this provider:

npm install @hot-updater/firebase --save-dev

An agent can perform these steps after inspecting the app's package manager and build configuration.

Step 2: Configure Firebase

Choose how to set up Firebase:

$hot-updater Set up infrastructure on Firebase for this project.

After setup, review the local configuration. Interactive init writes the settings below to .env.hotupdater; an agent merges the needed settings into your project. The project, region, Firestore database, and canonical bucket are persisted for deterministic reruns. Init doesn't create named Firestore databases: to keep Hot Updater in a named database, create it first and select it. With --env-file, init uses HOT_UPDATER_FIREBASE_DATABASE_ID, or (default) when it is unset. When no credential-file path is supplied, init can write the active placeholder GOOGLE_APPLICATION_CREDENTIALS=your-credentials.json. If you use existing application-default credentials (ADC), remove or comment out that line before running deploy or any command that loads hot-updater.config.ts; otherwise the Admin SDK tries to load the nonexistent file. Keep a credential-file assignment only when it points to your intended private local file.

HOT_UPDATER_FIREBASE_PROJECT_ID=your-project-id
HOT_UPDATER_FIREBASE_REGION=your-functions-region
HOT_UPDATER_FIREBASE_DATABASE_ID=(default)
HOT_UPDATER_FIREBASE_STORAGE_BUCKET=your-bucket-name
HOT_UPDATER_API_KEY=your-api-key
# Optional: only if using a private credential file instead of existing ADC
# GOOGLE_APPLICATION_CREDENTIALS=/private/path/your-credentials.json

Managed init reuses HOT_UPDATER_API_KEY when supplied or creates an API key, registers it in Firestore, and persists the plaintext value locally. Send this API key in the app's x-api-key request header. To list, add, or revoke keys later, run hot-updater api-key from the app directory.

Optional: Bundle signing

Managed Firebase init does not create or enable a signing key. The built-in local config works without a signing adapter. For non-exportable key custody, use the Google Cloud KMS signer from hot-updater/signing; signing is independent of storage and database choice. Embed the chosen public key in a native release before deploying signed bundles. Signing credentials belong in the deploy environment, never in the React Native app.

Step 3: Add HotUpdater to your project

After provisioning, record these outputs for Set up your app:

Use the actual URL returned by deployment. Configure the SDK and native bundle loader through Set up your app, using the selected build adapter and the same update strategy as hot-updater.config.ts. Only the client API key belongs in the mobile app's build-time configuration; provider credentials stay in the deploy environment.

Generated configuration and operations

Init generates hot-updater.config.ts with your Firebase storage and database, and plugins: the server plugins the managed Cloud Function runs, apiKeys(), insights(), and remoteConfig(), imported from hot-updater/plugins. The CLI and the Console reach Firestore and Cloud Storage through these settings and run the same plugins as the Cloud Function. The managed Cloud Function runs these official plugins only; to run other server plugins, use a custom server.

On a rerun, init updates storage, database, and plugins in the existing file and keeps your other settings, including a wrapped build such as withSentry(bare()) and the credential your config already sets. When it cannot edit hot-updater.config.ts, such as a config that a function returns, it leaves the file unchanged and prints the storage, database, and plugins lines to add.

.env.hotupdater contains provider settings and an optional credential-file path. Reuse working application-default credentials first. Set GOOGLE_APPLICATION_CREDENTIALS only when a private local credential file is needed; downloading a new key is not required when ADC already works. A Firebase CLI login alone does not necessarily authenticate the local Admin SDK. See Firebase Admin setup.

HOT_UPDATER_FIREBASE_PROJECT_ID=your-project-id
HOT_UPDATER_FIREBASE_REGION=your-functions-region
HOT_UPDATER_FIREBASE_DATABASE_ID=(default)
HOT_UPDATER_FIREBASE_STORAGE_BUCKET=your-bucket-name
HOT_UPDATER_API_KEY=your-api-key
# Optional: only if using a private credential file instead of existing ADC
# GOOGLE_APPLICATION_CREDENTIALS=/private/path/your-credentials.json

import { bare } from "@hot-updater/bare";
import { firebaseDatabase, firebaseStorage } from "@hot-updater/firebase";
import { apiKeys, insights, remoteConfig } from "hot-updater/plugins";
import { applicationDefault } from "firebase-admin/app";
import { defineConfig } from "hot-updater";
import { existsSync } from "node:fs";

if (existsSync(".env.hotupdater")) {
  process.loadEnvFile(".env.hotupdater");
}

// https://firebase.google.com/docs/admin/setup?hl=en#initialize_the_sdk_in_non-google_environments
// Reuse working application-default credentials (ADC).
// Only when a credential file is needed, set its private local path in .env.hotupdater:
// GOOGLE_APPLICATION_CREDENTIALS=./firebase-adminsdk-credentials.json
const credential = applicationDefault();

export default defineConfig({
  build: bare({ enableHermes: true }),
  storage: firebaseStorage({
    projectId: process.env.HOT_UPDATER_FIREBASE_PROJECT_ID!,
    storageBucket: process.env.HOT_UPDATER_FIREBASE_STORAGE_BUCKET!,
    credential,
  }),
  database: firebaseDatabase({
    projectId: process.env.HOT_UPDATER_FIREBASE_PROJECT_ID!,
    databaseId: process.env.HOT_UPDATER_FIREBASE_DATABASE_ID,
    credential,
  }),
  plugins: [apiKeys(), insights(), remoteConfig()],
  updateStrategy: "appVersion", // or "fingerprint"
});

Step 4: If you use Expo, add the config plugin

Follow the Expo path in Set up your app. It applies the config plugin and generates the native integration. For DOM components, continue with Expo DOM components.

Step 5: Add native code

For Bare or Rock, follow the Android and iOS instructions in Set up your app. Keep the integration appropriate to your React Native version and rebuild the native app after changing it.

Upgrade infrastructure

With the Hot Updater skill attached, ask your agent:

$hot-updater Upgrade this project's existing Firebase server infrastructure.

The agent discovers the existing deployment, uses hot-updater agent infra upgrade, and reads the applicable version files before changing resources. It applies pending changes and verifies the server with doctor. See Upgrade an existing server for the workflow or Doctor for terminal instructions.

For server templates to apply with your own deployment tooling, use hot-updater infra scaffold --provider firebase. See Infrastructure Templates.

Verifying the setup

1. Confirm the selected Firebase resources and the deployed client base URL.

2. From the React Native project, check the server and native integration:

   npx hot-updater doctor --server-base-url <client-base-url> --json

   Doctor checks the public /version endpoint. It does not prove an authenticated update download or application.

3. Complete Test an OTA update on a release build. Verify that the app downloads and runs the changed code, then survives a restart. With default signed Storage URLs, an actual artifact download also verifies the Function's signing API and IAM access; an empty catalog does not.

An agent should report the selected resources, verified URL, configuration file paths and verification result. Report a missing access, billing or native-build prerequisite explicitly instead of marking an untested installation complete.

Host the Console

Host the console on Vercel, Netlify, or Docker/Node with Firebase Admin SDK credentials. Cloud Run is another option when you want to use the existing Google Cloud project and service identity. See the console hosting matrix.