Configure Hosting behavior

With Firebase Hosting, you can configure customized hosting behavior for requests to your site.

What can you configure for Hosting?

Where do you define your Hosting configuration?

You define your Firebase Hosting configuration in your firebase.json file. Firebase automatically creates your firebase.json file at the root of your project directory when you run the firebase init command.

Priority order of Hosting responses

The different Firebase Hosting configuration options described on this page can sometimes overlap. If there is a conflict, Hosting determines its response using the following priority order:

If you're using i18n rewrites, the exact-match and 404 handling priority order are expanded in scope to accommodate your "i18n content".

Specify which files to deploy

The default attributes — public and ignore — included in the default firebase.json file define which files in your project directory should be deployed to your Firebase project.

public

Required
The public attribute specifies which directory to deploy to Firebase Hosting. The default value is a directory named public, but you can specify any directory's path, as long as it exists in your project directory.

ignore

Optional
The ignore attribute specifies the files to ignore on deploy. It can take globs the same way that Git handles .gitignore.

Customize a 404/Not Found page

Optional
You can serve a custom 404 Not Found error when a user tries to access a page that doesn't exist.

Create a new file in your project's public directory, name it 404.html, then add your custom 404 Not Found content to the file.

Firebase Hosting will display the content of this custom 404.html page if a browser triggers a 404 Not Found error on your domain or subdomain.

Configure redirects

Optional
Use a URL redirect to prevent broken links if you've moved a page or to shorten URLs. For example, you could redirect a browser from example.com/team to example.com/about.html.

Specify URL redirects by creating a redirects attribute that contains an array of objects (called "redirect rules"). In each rule, specify a URL pattern that, if matched to the request URL path, triggers Hosting to respond with a redirect to the specified destination URL.

Here's the basic structure for a redirects attribute. This example redirects requests to /foo by making a new request to /bar.

The redirects attribute contains an array of redirect rules, where each rule must include the fields in the table below.

Firebase Hosting compares the source or regex value against all URL paths at the start of every request (before the browser determines whether a file or folder exists at that path). If a match is found, then the Firebase Hosting origin server sends an HTTPS redirect response telling the browser to make a new request at the destination URL.

Capture URL segments for redirects

Field	Description
`redirects`
	`source` (recommended) or `regex`	A URL pattern that, if matched to the initial request URL, triggers Hosting to apply the redirect Use `source` to specify a glob (recommended). Use `regex` to specify a RE2 regular expression.
	`destination`	A static URL where the browser should make a new request This URL can be a relative or an absolute path.
	`type`	The HTTPS response code Use a type of `301` for 'Moved Permanently' Use a type of `302` for 'Found' (Temporary Redirect)

Optional
Sometimes, you might need to capture specific segments of a redirect rule's URL pattern (source or regex value), then re-use these segments in the rule's destination path.

If you're using a source field (that is, specifying a glob for your URL pattern), you can capture segments by including a : prefix to identify the segment. If you also need to capture the remaining URL path after the segment, include a * immediately after the segment. For example:

If you're using a regex field (that is, specifying a RE2 regular expression for your URL pattern), you can capture segments using either named or unnamed RE2 capture groups. Named capture groups can be used in the destination field with a : prefix, while unnamed capture groups can be referenced by their numerical index in the regex value, indexed from 1. For example:

Configure rewrites

Optional
Use a rewrite to show the same content for multiple URLs. Rewrites are particularly useful with pattern matching, as you can accept any URL that matches the pattern and let the client-side code decide what to display.

You can also use rewrites to support apps that use HTML5 pushState for navigation. When a browser attempts to open a URL path that matches the specified source or regex URL pattern, the browser will be given the contents of the file at the destination URL instead.

Specify URL rewrites by creating a rewrites attribute that contains an array of objects (called "rewrite rules"). In each rule, specify a URL pattern that, if matched to the request URL path, triggers Hosting to respond as if the service were given the specified destination URL.

Here's the basic structure for a rewrites attribute. This example serves index.html for requests to files or directories that don't exist.

The rewrites attribute contains an array of rewrite rules, where each rule must include the fields in the table below.

Firebase Hosting only applies a rewrite rule if a file or directory does not exist at a URL path that matches the specified source or regex URL pattern. When a request triggers a rewrite rule, the browser returns the actual content of the specified destination file instead of an HTTP redirect.

Direct requests to a function

Field	Description
`rewrites`
	`source` (recommended) or `regex`	A URL pattern that, if matched to the initial request URL, triggers Hosting to apply the rewrite Use `source` to specify a glob (recommended). Use `regex` to specify a RE2 regular expression.
	`destination`	A local file that must exist This URL can be a relative or an absolute path.

For example, to direct all requests from the page /bigben on your Hosting site to execute the bigben function:

After adding this rewrite rule and deploying to Firebase (using firebase deploy), your function is reachable via the following URLs:

When Firebase Hosting forwards traffic to a function, the function receives the full original request path and query string. For example, a request to /bigben/hello/world?foo=bar on your Hosting site is passed to the function with the complete path and query intact. Make sure your function handler is written to handle the entire absolute URL, not just the base path defined in the rewrite.

When redirecting requests to functions with Hosting, supported HTTP request methods are GET, POST, HEAD, PUT, DELETE, PATCH, and OPTIONS. Other methods like REPORT or PROFIND are not supported.

Direct requests to a Cloud Run container

You can use rewrites to access a Cloud Run container from a Firebase Hosting URL. The following example is an excerpt from serving dynamic content using Cloud Run.

For example, to direct all requests from the page /helloworld on your Hosting site to trigger the startup and running of a helloworld container instance:

After adding this rewrite rule and deploying to Firebase (using firebase deploy), your container image is reachable via the following URLs:

When redirecting requests to Cloud Run containers with Hosting, supported HTTP request methods are GET, POST, HEAD, PUT, DELETE, PATCH, and OPTIONS. Other methods like REPORT or PROFIND are not supported.

For the best performance, colocate your Cloud Run service with Hosting using the following regions:

Create custom domain Dynamic Links

Configure headers

Field	Description
`appAssociation`	Must be set to `AUTO` If you don't include this attribute in your configuration, the default for `appAssociation` is `AUTO`. By setting this attribute to `AUTO`, Hosting can dynamically generate `assetlinks.json` and `apple-app-site-association` files when they're requested.
`rewrites`
	`source`	A path that you want to use for Dynamic Links Unlike rules that rewrite paths to URLs, rewrite rules for Dynamic Links can't contain regular expressions.
	`dynamicLinks`	Must be set to `true`

Optional
Headers allow the client and the server to pass additional information along with a request or a response. Some sets of headers can affect how the browser handles the page and its content, including access control, authentication, caching, and encoding.

Specify custom, file-specific response headers by creating a headers attribute that contains an array of header objects. In each object, specify a URL pattern that, if matched to the request URL path, triggers Hosting to apply the specified custom response headers.

Here's the basic structure for a headers attribute. This example applies a CORS header for all font files.

View a more detailed example for a headers attribute

"hosting": {
  // ...

  // Add the "headers" attribute within "hosting"
  "headers": [ {
    // Applies a CORS header for all font files
    "source": "**/*.@(eot|otf|ttf|ttc|woff|font.css)",
    "headers": [ {
      "key": "Access-Control-Allow-Origin",
      "value": "*"
    } ]
  }, {
    // Overrides the default 1 hour browser cache with a 2 hour cache for all image files
    "source": "**/*.@(jpg|jpeg|gif|png)",
    "headers": [ {
      "key": "Cache-Control",
      "value": "max-age=7200"
    } ]
  }, {
    // A regular expression-based rewrite equivalent to the above behavior
    "regex": ".+/\w+\.(jpg|jpeg|gif|png)$",
    "headers": [ {
      "key": "Cache-Control",
      "value": "max-age=7200"
    } ]
  }, {
    // Sets the cache header for 404 pages to cache for 5 minutes
    "source": "404.html",
    "headers": [ {
      "key": "Cache-Control",
      "value": "max-age=300"
    } ]
  } ]
}

The headers attribute contains an array of definitions, where each definition must include the fields in the table below.

Field			Description
`headers`
	`source` (recommended) or `regex`		A URL pattern that, if matched to the initial request URL, triggers Hosting to apply the custom header Use `source` to specify a glob (recommended). Use `regex` to specify a RE2 regular expression. To create a header to match against your custom 404 page, use `404.html` as your `source` or `regex` value.
	array of (sub-)`headers`		The custom headers that Hosting applies to the request path Each sub-header must include a `key` and `value` pair (see next two rows).
		`key`	The name of the header, for example `Cache-Control`
		`value`	The value for the header, for example `max-age=7200`

You can learn more about Cache-Control in the Hosting section that describes serving dynamic content and hosting microservices. You can also learn more about CORS headers.

Control `.html` extensions

Optional
The cleanUrls attribute allows you to control whether or not URLs should include the .html extension.

When true, Hosting automatically drops the .html extension from uploaded file URLs. If an .html extension is added in the request, Hosting performs a 301 redirect to the same path but eliminates the .html extension.

Here's how to control the inclusion of .html in URLs by including a cleanUrls attribute:

"hosting": {
  // ...

  // Drops `.html` from uploaded URLs
  "cleanUrls": true
}

Control trailing slashes

Optional
The trailingSlash attribute allows you to control whether or not static content URLs should include trailing slashes.

When true, Hosting redirects URLs to add a trailing slash.
When false, Hosting redirects URLs to remove a trailing slash.
When unspecified, Hosting only uses trailing slashes for directory index files (for example, about/index.html).

Here's how to control trailing slashes by adding a trailingSlash attribute:

"hosting": {
  // ...

  // Removes trailing slashes from URLs
  "trailingSlash": false
}

The trailingSlash attribute does not affect rewrites to dynamic content served by Cloud Functions or Cloud Run.

Glob pattern matching

Firebase Hosting configuration options make extensive use of the glob pattern matching notation with extglob, similar to how Git handles gitignore rules and Bower handles ignore rules. This wiki page is a more detailed reference, but the following are explanations of examples used on this page:

firebase.json — Only matches the firebase.json file in the root of the public directory
** — Matches any file or folder in an arbitrary sub-directory
* — Only matches files and folders in the root of the public directory
**/.* — Matches any file beginning with . (usually hidden files, like in the .git folder) in an arbitrary sub-directory
**/node_modules/** — Matches any file or folder in an arbitrary sub-directory of a node_modules folder, which can itself be in an arbitrary sub-directory of the public directory
**/*.@(jpg|jpeg|gif|png) — Matches any file in an arbitrary sub-directory that ends with exactly one of the following: .jpg, .jpeg, .gif, or .png

Full Hosting configuration example

The following is a full firebase.json configuration example for Firebase Hosting. Note that a firebase.json file can also contain configurations for other Firebase services.

{
  "hosting": {

    "public": "dist/app",  // "public" is the only required attribute for Hosting

    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],

    "redirects": [ {
      "source": "/foo",
      "destination": "/bar",
      "type": 301
    }, {
      "source": "/firebase/**",
      "destination": "https://www.firebase.com",
      "type": 302
    } ],

    "rewrites": [ {
      // Shows the same content for multiple URLs
      "source": "/app/**",
      "destination": "/app/index.html"
    }, {
      // Configures a custom domain for Dynamic Links
      "source": "/promos/**",
      "dynamicLinks": true
    }, {
      // Directs a request to Cloud Functions
      "source": "/bigben",
      "function": "bigben"
    }, {
      // Directs a request to a Cloud Run containerized app
      "source": "/helloworld",
      "run": {
        "serviceId": "helloworld",
        "region": "us-central1"
      }
    } ],

    "headers": [ {
      "source": "**/*.@(eot|otf|ttf|ttc|woff|font.css)",
      "headers": [ {
        "key": "Access-Control-Allow-Origin",
        "value": "*"
      } ]
    }, {
      "source": "**/*.@(jpg|jpeg|gif|png)",
      "headers": [ {
        "key": "Cache-Control",
        "value": "max-age=7200"
      } ]
    }, {
      "source": "404.html",
      "headers": [ {
        "key": "Cache-Control",
        "value": "max-age=300"
      } ]
    } ],

    "cleanUrls": true,

    "trailingSlash": false,

    // Required to configure custom domains for Dynamic Links
    "appAssociation": "AUTO",

  }
}

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-06-12 UTC.