Why is my API route serving index.html instead of hitting my Cloud Run service?

Rewrite order. If a broader pattern like `**` appears before your more specific `/api/**` rewrite in the array, Hosting matches it first and never evaluates the later rule. Rewrites are first-match-wins in array order, not most-specific-match-wins, so put the SPA catch-all last.

Does changing cleanUrls or trailingSlash affect already-indexed pages?

Yes, it changes which URL shape is canonical going forward, and search engines that indexed the old form (with or without .html, with or without trailing slash) may show stale or duplicate entries until they recrawl. If you must change either setting post-launch, pair it with redirects from the old shape to the new one rather than just flipping the flag.

What's the difference between the run and function rewrite targets?

run routes matching requests to a Cloud Run service in a specified region, giving you a full container; function routes to a Cloud Function by ID and region. Both integrate behind Hosting's CDN and SSL, the choice is purely about which compute product your backend actually runs on, not a Hosting-level tradeoff.

GCP Firebase Hosting Config Builder

ServerlessGCP

Build Firebase Hosting configurations with rewrites, redirects, custom headers, and Cloud Run integration.

Firebase Hosting Configuration

Build Firebase Hosting configurations with rewrites, redirects, custom headers, Cloud Run integration, and caching rules.

Required Fields

hosting.sitehosting.publichosting.rewrites

{
  "hosting": {
    "site": "my-project-web",
    "public": "dist",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "/api/**",
        "run": {
          "serviceId": "api-service",
          "region": "us-central1"
        }
      },
      {
        "source": "/auth/**",
        "function": {
          "functionId": "authHandler",
          "region": "us-central1"
        }
      },
      {
        "source": "**",
        "destination": "/index.html"
      }
    ],
    "redirects": [
      {
        "source": "/old-page",
        "destination": "/new-page",
        "type": 301
      },
      {
        "source": "/blog/:slug",
        "destination": "/articles/:slug",
        "type": 302
      }
    ],
    "headers": [
      {
        "source": "**/*.@(js|css)",
        "headers": [
          {
            "key": "Cache-Control",
            "value": "public, max-age=31536000, immutable"
          }
        ]
      },
      {
        "source": "**",
        "headers": [
          {
            "key": "X-Frame-Options",
            "value": "DENY"
          },
          {
            "key": "X-Content-Type-Options",
            "value": "nosniff"
          },
          {
            "key": "Strict-Transport-Security",
            "value": "max-age=63072000; includeSubDomains; preload"
          }
        ]
      }
    ],
    "cleanUrls": true,
    "trailingSlash": false,
    "i18n": {
      "root": "/localized-files"
    }
  }
}

Generated Output

Output will appear here...

About This Tool

Build a Firebase Hosting configuration covering rewrites, redirects, custom headers, and Cloud Run/Functions integration. Rewrites are evaluated in the order they appear and the first matching glob wins, so a catch-all `**` rewrite to /index.html must come last or it swallows every more-specific rule declared after it, a classic single-page-app misconfiguration. cleanUrls strips .html from served paths and trailingSlash controls whether Hosting normalizes a trailing slash away or adds one, both affect canonical URLs and, if changed after launch, can quietly create duplicate-content issues for anything that was indexed under the old URL shape.

Real-World Scenario

A team deploys a new /api/** rewrite pointing at a freshly-launched Cloud Run backend, but every request to it comes back with the SPA's HTML shell instead of JSON, and the Cloud Run logs show zero incoming traffic at all despite the frontend clearly making the calls. The rewrites array has the SPA's catch-all `**` to /index.html declared before the new /api/** entry, added months earlier and never revisited. They use the builder to reorder the array with /api/** and /auth/** first and the catch-all strictly last, redeploy, and traffic starts reaching the Cloud Run service on the very next request.

When to Use This Tool

•Ordering rewrites so /api/** routes to a Cloud Run service via the run block and /auth/** routes to a Cloud Function, with the SPA catch-all `**` to /index.html placed last so it doesn't intercept either API path.
•Adding immutable Cache-Control headers for hashed JS/CSS bundle output while leaving HTML responses uncached, so a deploy doesn't get masked behind a stale cached index.html for returning visitors.
•Debugging why an /api/** request is being served the SPA's index.html instead of hitting the Cloud Run backend, tracing it to a broader catch-all rewrite declared earlier in the array.
•Setting a 301 redirect for a retired route to its replacement so existing backlinks and bookmarks don't 404 after a site restructure.

Pro Tips

TIP

Rewrite array order is load-bearing — always put narrower path patterns before broader ones, and the SPA fallback `**` rewrite absolute last, or specific routes silently stop working after someone adds a new broad rule above them.

TIP

Cache-Control headers on hashed asset filenames (content-hash in the name) can safely use max-age=31536000, immutable since a content change produces a new filename; the same header on unhashed files like index.html causes stale deploys to persist in browsers for up to a year.

TIP

i18n content negotiation via the root config only affects paths under that root; requests outside it fall back to default content, a mismatch here is a common cause of one locale silently not localizing while others work fine.

How It Works Under the Hood

The builder requires hosting.site, hosting.public, and hosting.rewrites to resolve before treating the JSON as deployable, the minimum Firebase needs to know which site, which local directory maps to it, and how requests route, everything else (headers, redirects, i18n) layers on top as optional but structurally-validated JSON.

Frequently Asked Questions

Why is my API route serving index.html instead of hitting my Cloud Run service?: Rewrite order. If a broader pattern like `**` appears before your more specific `/api/**` rewrite in the array, Hosting matches it first and never evaluates the later rule. Rewrites are first-match-wins in array order, not most-specific-match-wins, so put the SPA catch-all last.
Does changing cleanUrls or trailingSlash affect already-indexed pages?: Yes, it changes which URL shape is canonical going forward, and search engines that indexed the old form (with or without .html, with or without trailing slash) may show stale or duplicate entries until they recrawl. If you must change either setting post-launch, pair it with redirects from the old shape to the new one rather than just flipping the flag.
What's the difference between the run and function rewrite targets?: run routes matching requests to a Cloud Run service in a specified region, giving you a full container; function routes to a Cloud Function by ID and region. Both integrate behind Hosting's CDN and SSL, the choice is purely about which compute product your backend actually runs on, not a Hosting-level tradeoff.

Related Learning Guides

Cloud Functions vs Cloud Run24 min read
Pub/Sub & Event-Driven Architecture25 min read

Was this tool helpful?

Disclaimer: This tool runs entirely in your browser. No data is sent to our servers. Always verify outputs before using them in production. AWS, Azure, and GCP are trademarks of their respective owners.