You're viewing the legacy docs. They are deprecated as of May 18, 2016.
Go to current docs

Hosting Guide

URL Redirects & Rewrites

Firebase Hosting has some additional features that let you customize how your app is hosted. This article covers custom error pages, redirects, rewrites and headers.

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 root of your 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 in the firebase.json file:

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

The redirects setting is an optional parameter since v1.1.0 of firebase-tools 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 in the firebase.json file:

"rewrites": [ {
  "source": "**",
  "destination": "/index.html"
} ]

The rewrites setting is an optional parameter since v1.1.0 of firebase-tools 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 in the firebase.json file:

"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 since v1.1.0 of firebase-tools 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 exception to this rule is when a file or folder cannot be found and instead gets matched against the string 404.html to allow specifically targeting error pages.

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

Make sure to upgrade to the latest version of the Firebase CLI to have access to all these headers:

$ npm update -g firebase-tools