Firebase Hosting skill for Codex

A clean Firebase Hosting setup serves hashed assets with long cache lifetimes and HTML with short ones, routes /api/** to a function or Cloud Run service in the same project, gives every pull request its own expiring preview channel, and deploys --only hosting so a site change never redeploys unrelated functions or rules.

Inspect first

1. Read AGENTS.md, firebase.json, .firebaserc (project aliases and targets), the framework build output directory, and functions/ or Cloud Run source if present.
2. Run firebase use to see the active project alias. Deploying to the wrong alias is the most common incident. firebase commands that touch projects need network and login (firebase login, or a service account in CI).
3. Decide the product:

App	Product
Static site, SPA (React, Vue, Angular CSR), docs	Firebase Hosting
Static site plus a small API	Hosting with rewrites to Cloud Functions or Cloud Run
Next.js or Angular with SSR as the main app	Firebase App Hosting (apphosting.yaml, Git-based rollouts), not classic Hosting
Container you already run on Cloud Run	Hosting rewrite to Cloud Run for the custom domain and CDN

firebase.json baseline

{
  "hosting": {
    "public": "dist",
    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
    "cleanUrls": true,
    "trailingSlash": false,
    "redirects": [
      { "source": "/blog/:slug", "destination": "/articles/:slug", "type": 301 }
    ],
    "rewrites": [
      { "source": "/api/**", "function": { "functionId": "api", "region": "us-central1" } },
      { "source": "/render/**", "run": { "serviceId": "renderer", "region": "europe-west1" } },
      { "source": "**", "destination": "/index.html" }
    ],
    "headers": [
      {
        "source": "**/*.@(js|css|woff2|png|jpg|webp|avif|svg)",
        "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
      },
      {
        "source": "**/*.html",
        "headers": [{ "key": "Cache-Control", "value": "no-cache" }]
      }
    ]
  }
}

Rules:

• Hosting serves an existing static file before evaluating rewrites, so the ** SPA fallback is safe. Redirects are evaluated before files.
• Rewrites match in order; put specific API rules before the catch-all.
• Long cache headers only on hashed filenames. Unhashed assets with a one-year immutable header cannot be updated in browsers.
• The region in a function rewrite must match where the function is deployed.

API behind Hosting

// functions/src/index.ts
import { onRequest } from "firebase-functions/v2/https";
import express from "express";

const app = express();
app.get("/api/products", async (_req, res) => {
  res.set("Cache-Control", "public, max-age=60, s-maxage=300");
  res.json(await listProducts());
});

export const api = onRequest({ region: "us-central1", memory: "512MiB", concurrency: 80 }, app);

• The Express route must include the /api prefix: Hosting forwards the full path.
• Hosting’s CDN caches function and Cloud Run responses only when they send Cache-Control with public and s-maxage (or max-age). Without it every request invokes the function.
• Cookies are stripped from requests forwarded to functions and Cloud Run, except one named __session. Use that name for the session cookie.
• Requests proxied through Hosting have a fixed timeout around one minute even if the function allows longer; long work must be asynchronous.

Multiple sites and targets

firebase target:apply hosting marketing acme-marketing
firebase target:apply hosting app acme-app

{
  "hosting": [
    { "target": "marketing", "public": "apps/marketing/dist" },
    { "target": "app", "public": "apps/web/dist", "rewrites": [{ "source": "**", "destination": "/index.html" }] }
  ]
}

firebase deploy --only hosting:app

Local loop and deploys

firebase emulators:start --only hosting,functions     # serves on localhost; works offline after install
firebase hosting:channel:deploy pr-123 --expires 7d    # preview URL, does not touch live
firebase hosting:channel:list
firebase deploy --only hosting -m "release 2026-10-28" # live: confirm with the user first
firebase hosting:clone acme-app:pr-123 acme-app:live   # promote a tested preview to live (confirm first)

Preview channels share the project’s backend (Firestore, Functions). A preview is not an isolated staging environment; use a separate Firebase project for that and switch with firebase use staging.

Rollback: in the console’s Hosting release history choose “Rollback”, or clone a known good channel or version to live. Only static content and config roll back; functions and databases do not.

GitHub Actions

firebase init hosting:github creates workflows that deploy a preview channel per PR and live on merge using FirebaseExtended/action-hosting-deploy. Review the generated service account: it gets deploy permissions to the project, so store its key as a repository secret, or prefer Workload Identity Federation with google-github-actions/auth to avoid long-lived keys.

- uses: FirebaseExtended/action-hosting-deploy@v0
  with:
    repoToken: ${{ secrets.GITHUB_TOKEN }}
    firebaseServiceAccount: ${{ secrets.FIREBASE_SERVICE_ACCOUNT }}
    projectId: acme-app
    expires: 7d

Debug table

Symptom	Check
Deep link returns 404	Missing ** rewrite to /index.html, or wrong public directory
/api returns the SPA HTML	API rewrite after the catch-all, or function name or region mismatch
Function returns 404 for /api/x	Express routes defined without the /api prefix
Logged-in user loses session through Hosting	Cookie not named __session
Function invoked on every request despite caching	No public plus s-maxage in the response
Old site after deploy	Long max-age on HTML or unhashed assets; a stale service worker

Verification

• firebase emulators:start serves the site; routes, rewrites and headers behave as expected.
• A preview channel URL passes smoke tests; curl -sI shows intended Cache-Control.
• firebase use shows the intended project before every deploy.
• Live deploys and clone-to-live happen only after explicit user approval.

Gotchas

• firebase deploy without --only deploys everything configured: functions, rules, indexes. Always scope it.
• Hosting custom domains need DNS records verified; certificate provisioning can take a while after DNS changes.
• The ignore list does not stop secrets in the build output from being published. Audit public for .env files and source maps you do not want public.
• Each Hosting site keeps a capped number of releases; older ones are deleted automatically, so long-term rollback relies on rebuilding from git.