Customize Hosting Behavior

Custom 404/Not Found page

You can specify a custom 404/Not Found error to be served when a user tries to access a page that does not exist. Simply add a 404.html page to the your project's public directory and the contents of this page will be displayed when Firebase Hosting needs to display a 404 Not Found error to the user.

Redirects

URL redirects can be used to prevent broken links if a page has moved, or for URL shortening. When a browser attempts to open a specified source URL it will instead open the destination URL, updating the location of the browser to that destination URL. For example, you could redirect example.com/team to example.com/about.html.

URL redirects can be specified by defining a redirects section within hosting in the firebase.json file:

"hosting": {
  // Add the "redirects" section within "hosting"
  "redirects": [ {
    "source" : "/foo",
    "destination" : "/bar",
    "type" : 301
  }, {
    "source" : "/firebase/*",
    "destination" : "https://firebase.google.com",
    "type" : 302
  } ]
}

The redirects setting is an optional parameter that contains an array of redirect rules. Each rule must specify a source, destination, and type.

The source parameter is a glob pattern that is matched against all URL paths at the start of every request (before it is determined whether a file or folder exists at that path). If a match is found, an HTTP redirect response is set with the "Location" header set to the static destination string, which can be a relative path or an absolute URL.

Finally, the type parameter specifies the specific HTTP response code served and can either be 301 for 'Moved Permanently' or 302 for 'Found' (Temporary Redirect).

Rewrites

Use a rewrite when you want 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. Rewrite rules can be used to support apps using HTML5 pushState for navigation. When a browser attempts to open a specified source URL it will be given the contents of the file at the destination URL.

URL rewrites can be specified by defining a rewrites section within hosting in the firebase.json file:

"hosting": {
  // Add the "rewrites" section within "hosting"
  "rewrites": [ {
    "source": "**",
    "destination": "/index.html"
  } ]
}

The rewrites setting is an optional parameter that contains an array of internal rewrite rules. Similar to redirects above, each rewrite rule must have a source glob pattern and a local destination (which should exist and be a file). A rewrite rule is only applied if a file or folder does not exist at the specified source, and returns the actual content of the file at the destination instead of an HTTP redirect.

The example above redirects any file in any folder to /index.html if a file does not exist - handy for apps utilizing HTML5 pushState.

Headers

Custom, file specific, headers can be specified by defining a headers section within hosting in the firebase.json file:

"hosting": {
    // Add the "headers" section within "hosting".
    "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"
      } ]
    }, {
      // 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 setting is an optional parameter that contains an array of custom header definitions. Each definition must have a source key that is matched against the original request path regardless of any rewrite rules using glob notation. Each definition must also have an array of headers to be applied, each with a key and a value.

The example above specifies a CORS header for all font files and overrides the default one hour browser cache with a two hour cache for image files. We currently support the following headers as a key:

• Cache-Control
• Access-Control-Allow-Origin
• X-UA-Compatible
• X-Content-Type-Options
• X-Frame-Options
• X-XSS-Protection
• Content-Type
• Link
• Content-Security-Policy

You can see all available configuration options in the Deployment Configuration reference.

Hosting Priorities

The different options can sometimes overlap. If there is a conflict, the response from Firebase Hosting will be determined in priority order. From highest to lower priority these are:

1. Reserved namespace (/__*)
2. Configured redirects
3. Exact-match static content
4. Configured rewrites
5. Custom 404 page
6. Default 404 page