gatsby-plugin-gatsby-cloud

The gatsby-plugin-gatsby-cloud plugin enables hosting and CMS preview features on Gatsby Cloud. This includes:

• redirect configuration
• custom header configuration
• Preview Status Indicator (Gatsby v3.6 and later)

By default, Gatsby Cloud will install the plugin for you, however it's best to add it as a dependency for your project manually.

Install

npm install --save gatsby-plugin-gatsby-cloud

How to Use

If no special configuration is necessary, you can use the plugin like this:

plugins: [`gatsby-plugin-gatsby-cloud`]

Configuration

The following header and redirect configuration options are provided:

plugins: [
  {
    resolve: `gatsby-plugin-gatsby-cloud`,
    options: {
      headers: {},
      allPageHeaders: [],
      mergeSecurityHeaders: true,
      mergeLinkHeaders: true,
      mergeCachingHeaders: true,
      transformHeaders: (headers, path) => headers
      generateMatchPathRewrites: true,
    },
  },
]

Options

Descriptions for the available plugin options are provided below:

Headers

After a build, the plugin generates a _headers.json at the root of the public folder, which is used to configure your headers on Gatsby Hosting.

Defaults

When mergeSecurityHeaders is enabled, the following default security headers are set for all routes:

X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin

When mergeCachingHeaders is enabled, the caching policy for gatsby build output JavaScript bundles, styles, and static assets are set to:

Cache-Control: public, max-age=31536000, immutable

Additionally, the service worker sw.js is set to:

Cache-Control: public, max-age=0, must-revalidate

When mergeLinkHeaders is enabled, default preloading headers for JSON page data and JS bundles are applied to tags.  In most cases, you don't want to disable this feature.

You should pass in an object with string keys (representing the paths) and an array of strings for each header.

An example:

{
  options: {
    headers: {
      "/*": [
        "Basic-Auth: someuser:somepassword anotheruser:anotherpassword",
      ],
      "/my-page": [
        // matching headers (by type) are replaced by Gatsby Cloud with more specific routes
        "Basic-Auth: differentuser:differentpassword",
      ],
    },
  }
}

Link Path Handling

Link paths are specially handled by this plugin. Since most files are processed and cache-busted through Gatsby (with a file hash), the plugin will transform any base file names to the hashed variants. If the file is not hashed, it will ensure the path is valid relative to the output public folder. You should be able to reference assets imported through javascript in the static folder.

Do not specify the public path in the config, as the plugin will provide it for you.

Header Inheritance

Headers are not inherited. This means that headers matching rules for more specific routes override those of less specific routes. For example, if you add a link to the root wildcard path (/*), it will be replaced by any more specific path. If you want a resource to be linked across the site, you will have to add to every path. To make this easier, the plugin provides the allPageHeaders option to inject the same headers on every page path.

{
  options: {
    allPageHeaders: [
      "Link: ; rel=preload; as=image",
    ],
    headers: {
      "/*": [
        "Basic-Auth: someuser:somepassword anotheruser:anotherpassword",
      ],
    },
  }
}

Changing Default Headers

You may have a use case that requires making a change to one of the default security headers. You might have social media embeds on your site, for instance, that the Referrer-Policy: same-originheader prevents from rendering. In this scenario, you can adjust the default plugin headers:

{
  resolve: 'gatsby-plugin-gatsby-cloud',
  options: {
    headers: {
       "/*": [ 
         'Referrer-Policy: strict-origin-when-cross-origin'
       ]
    }
  }
}

Redirects

You can create redirects using the createRedirect action as you normally would. After a build, the plugin generates a _redirects.json file at the root of the public folder, which is used to configure your redirects on Gatsby Hosting.

See the Working with Redirects guide for details on specific redirect use cases.

In addition to the options provided by the Gatsby API, you can pass these options specific to this plugin:

The ignoreCase, force , and rest  options are not supported.

Client-only Redirect Handling

When generateMatchPathRewrites is enabled, redirect rules are automatically added for client only paths. The plugin uses the matchPath syntax to match all possible requests in the range of your client-side routes and serves the HTML file for the client-side route. Without it, only the exact route of the client-side route works.

If those rules are conflicting with custom rules or if you want to have more control over them you can disable them in configuration by setting generateMatchPathRewrites to false.

Pattern Matching

An asterisk wildcard, *, will match anything that follows a path. RegEx and shell terminal-style glob pattern matching is not supported.

HTTP Strict Transport Security

HSTS Cheatsheet

Since this header is an opt-in security enhancement with permanent consequences we don't include it as a default feature but use the allPagesHeaders to include it.

{
  options: {
    allPageHeaders: [
      "Strict-Transport-Security: max-age=31536000; includeSubDomains; preload",
    ],
  }
}