Firebase App Hosting Basics

App Hosting Basics

Description

This skill enables the agent to deploy and manage modern, full-stack web applications (Next.js, Angular, etc.) using Firebase App Hosting.

Important: In order to use App Hosting, your Firebase project must be on the Blaze pricing plan. Direct the user to https://console.firebase.google.com/project/_/overview?purchaseBillingPlan=metered to upgrade their plan.

Hosting vs App Hosting

Choose Firebase Hosting if:

• You are deploying a static site (HTML/CSS/JS).
• You are deploying a simple SPA (React, Vue, etc. without SSR).
• You want full control over the build and deploy process via CLI.

Choose Firebase App Hosting if:

• You are using a supported full-stack framework like Next.js or Angular.
• You need Server-Side Rendering (SSR) or ISR.
• You want an automated "git push to deploy" workflow with zero configuration.

Deploying to App Hosting

Deploy from Source

This is the recommended flow for most users.

1. Configure firebase.json with an apphosting block.

   {
     "apphosting": {
       "backendId": "my-app-id",
       "rootDir": "/",
       "ignore": [
         "node_modules",
         ".git",
         "firebase-debug.log",
         "firebase-debug.*.log",
         "functions"
       ]
     }
   }

1. Create or edit apphosting.yaml- see Configuration for more information on how to do so. 1. If the app needs safe access to sensitive keys, use npx -y firebase-tools@latest apphosting:secrets commands to set and grant access to secrets. 1. Run npx -y firebase-tools@latest deploy when you are ready to deploy.

Automated deployment via GitHub (CI/CD)

Alternatively, set up a backend connected to a GitHub repository for automated deployments "git push" deployments. This is only recommended for more advanced users, and is not required to use App Hosting. See CLI Commands for more information on how to set this up using CLI commands.

Emulation

See Emulation for more information on how to test your app locally using the Firebase Local Emulator Suite.

App Hosting CLI Commands

The Firebase CLI provides a comprehensive suite of commands to manage App Hosting resources. These commands are often faster and more scriptable than using the Firebase Console.

Initialization

npx -y firebase-tools@latest init apphosting

• Purpose: Interactive command that sets up App Hosting in your local

project. Use this command only if you are able to handle interactive CLI inputs well. Alternatively, you can manually edit firebase.json and apphosting.yml.

• Effect:

• Detects your web framework.
• Creates/updates apphosting.yaml.
• Can optionally create a backend if one doesn't exist.

Backend Management

npx -y firebase-tools@latest apphosting:backends:list

• Purpose: Lists all backends in the current project.

npx -y firebase-tools@latest apphosting:backends:get <backend-id>

• Purpose: Shows details for a specific backend.

npx -y firebase-tools@latest apphosting:backends:delete <backend-id>

• Purpose: Deletes a backend and its associated resources.

npx -y firebase-tools@latest apphosting:rollouts:list <backend-id>

• Purpose: Lists the history of rollouts for a backend.

Secrets Management

App Hosting uses Cloud Secret Manager to securely handle sensitive environment variables (like API keys).

npx -y firebase-tools@latest apphosting:secrets:set <secret-name>

• Purpose: Creates or updates a secret in Cloud Secret Manager and makes it

available to App Hosting.

• Behavior: Prompts for the secret value (hidden input).

npx -y firebase-tools@latest apphosting:secrets:grantaccess <secret-name>

• Purpose: Grants the App Hosting service account permission to access the

secret.

• Note: Often handled automatically by secrets:set, but useful for

debugging permission issues or granting access to existing secrets.

Automated deployment via GitHub (CI/CD)

IMPORTANT Only use these commands if you are setting up automated deployments via GitHub. If you are managing deployments using npx -y firebase-tools@latest deploy, DO NOT use these commands.

npx -y firebase-tools@latest apphosting:rollouts:create <backend-id>

• Purpose: Manually triggers a new rollout (deployment).
• Options:
• --git-branch <branch>: Deploy the latest commit from a specific branch.
• --git-commit <commit-hash>: Deploy a specific commit.
• Use Case: Useful for redeploying without code changes, or rolling back to

a specific commit.

npx -y firebase-tools@latest apphosting:backends:create

• Purpose: Creates a new App Hosting backend. Use this when setting up

automated deployments via GitHub.

• Options:
• --app <webAppId>: The ID of an existing Firebase web app to associate with

the backend.

• --backend <backendId>: The ID of the new backend.
• --primary-region <location>: The primary region for the backend.
• --root-dir <rootDir>: The root directory for the backend. If omitted,

defaults to the root directory of the project.

• --service-account <service-account>: The service account used to run the

server. If omitted, defaults to the default service account.

App Hosting Configuration (apphosting.yaml)

The apphosting.yaml file is the source of truth for your backend's configuration. It must be located in the root of your app's directory (or the specific root directory if using a monorepo).

File Structure

# apphosting.yaml

# Cloud Run service configuration
runConfig:
  cpu: 1
  memoryMiB: 512
  minInstances: 0
  maxInstances: 100
  concurrency: 80

# Environment variables
env:
  - variable: STORAGE_BUCKET
    value: mybucket.app
    availability:
      - BUILD
      - RUNTIME
  - variable: API_KEY
    secret: myApiKeySecret

runConfig

Controls the resources allocated to the Cloud Run service that serves your app.

• cpu: Number of vCPUs. Note: If < 1, concurrency MUST be set to 1.
• memoryMiB: RAM in MiB (128 to 32768).
• minInstances: Minimum containers to keep warm (default 0). Set to >= 1 to

avoid cold starts.

• maxInstances: Maximum scaling limit (default 100).
• concurrency: Max concurrent requests per instance (default 80).

Resource Constraints

• CPU vs Memory: Higher memory often requires higher CPU.
• > 4GiB RAM -> Needs >= 2 vCPU
• > 8GiB RAM -> Needs >= 4 vCPU

env (Environment Variables)

Defines environment variables available during build and/or runtime.

• variable: The name of the env var (e.g., NEXT_PUBLIC_API_URL).
• value: A literal string value.
• secret: The name of a secret in Cloud Secret Manager. use

npx -y firebase-tools@latest apphosting:secrets:set to create these.

• availability: Where the variable is needed.
• BUILD: Available during the npm run build process.
• RUNTIME: Available when the app is serving requests.
• Defaults to both if not specified.

App Hosting Emulation

You can test your App Hosting setup locally using the Firebase Local Emulator Suite. This allows you to verify your app's behavior with environment variables and secrets before deploying.

Configuration: apphosting.emulator.yaml

This optional file overrides apphosting.yaml settings specifically for the local emulator. Use it to provide local secret values or override resource configs. If it contains sensitive values such as API keys, do not commit it to source control.

# apphosting.emulator.yaml (gitignored usually)
runConfig:
  cpu: 1
  memoryMiB: 512

env:
  - variable: API_KEY
    value: "local-dev-api-key" # Override secret with local value

Running the Emulator

To start the App Hosting emulator:

npx -y firebase-tools@latest emulators:start --only apphosting

Or, if you are also using other emulators (Auth, Firestore, etc.):

npx -y firebase-tools@latest emulators:start

Capabilities

• Builds your app: Runs the build command defined in your package.json to

generate the serving artifact.

• Serves locally: Runs the app on localhost:5004 (default). Configurable

by setting host and port in the emulators block of firebase.json, like so:

{
  "emulators": {
    "apphosting": {
      "host": "localhost",
      "port": 5004
    }
  }
}

• Env Var Injection: Injects variables defined in apphosting.yaml and

apphosting.emulator.yaml into the process.