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

Hosting Guide

Full Configuration

The firebase.json File

The firebase init command creates a firebase.json settings file in the root of your project's directory. This required file is used to configure which files are published upon deployment. Your default firebase.json file will look like this:

{
  "firebase": "myfirebase",
  "public": "app",
  "ignore": [
    "firebase.json",
    "**/.*",
    "**/node_modules/**"
  ]
}

Default Properties

The file's three default properties - firebase, public, and ignore - are described in detail below.

firebase

"firebase": "myfirebase"

required - The firebase setting contains the name of the Firebase app to which your project will be linked. This will also be used as the subdomain on firebaseapp.com. The logged in user must have access to that Firebase app in order to deploy.

public

"public": "app"

required - The public setting tells the firebase command which directory to upload to Firebase Hosting. This directory must be inside the project directory and must exist. The default value is the project's root directory.

ignore

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

optional - The ignore setting is an optional parameter since v1.0.1 of firebase-tools that specifies files to ignore on deploy. It can take glob definitions the same way git handles .gitignore.

Advanced Properties

The firebase.json file has a few other optional paramaters that let you specify Security and Firebase Rules, redirects, rewrites, and headers for your app. You can see an example of a full firebase.json file here, and these optional parameters are explained in detail below:

rules

"rules": "config/security-rules.json"

optional - The rules setting is an optional parameter that specifies a JSON file containing Security and Firebase Rules for the app. If specified, these rules will be applied on each deploy.

If rules are specified in your firebase.json file they will overwrite any rules configured in your Firebase app's dashboard when you deploy.

redirects

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

optional - 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

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

optional - 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.

cleanUrls

"cleanUrls": true

optional - The cleanUrls setting is an optional parameter since v2.2.0 of firebase-tools that can automatically drop the .html extension from files in your site.

When true, all .html files will be served without their extensions, and if an extension is provided, it will redirect with a 301 status code to the clean version.

This option may also be set to a glob string that will only enable clean URLs for paths that match the glob.

trailingSlash

"trailingSlash": false

optional - The trailingSlash option may be set to true or false to force the presence or absence of trailing slashes on URLs, respectively. If not present, a slash will be enforced for directory indexes, ensuring proper relative URL resolution.

headers

"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"
    } ]
  } ]

optional - 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 targetting error pages.

The example above specifies a CORS header for all font files and overrides the default 1 hour browser cache with a 2 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

Glob Pattern Matching

The firebase.json definitions detailed above 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 great for a more detailed reference, but here's an explanation of the examples above:

  • firebase.json matches just the firebase.json file in the root of the public directory.
  • ** matches any file or folder in an arbitrary sub-directory. Note that * just matches files and folders in the root directory.
  • **/.* matches any file beginning with a '.' (usually hidden files, like 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 a '.' and exactly one of either 'jpg', 'jpeg', 'gif', or 'png'.

Full firebase.json Example

{
  "firebase": "myfirebase",
  "public": "app",
  "ignore": [
    "firebase.json",
    "**/.*",
    "**/node_modules/**"
  ],
  "cleanUrls": true,
  "trailingSlash": false,
  "rules": "config/security-rules.json",
  "redirects": [ {
    "source" : "/foo",
    "destination" : "/bar",
    "type" : 301
  }, {
    "source" : "/firebase/*",
    "destination" : "https://www.firebase.com",
    "type" : 302
  } ],
  "rewrites": [ {
    "source": "**",
    "destination": "/index.html"
  } ],
  "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"
    } ]
  } ]
}