🌜
🌞
gatsby-plugin-gatsby-cloud

gatsby-plugin-gatsby-cloud

v4.20.0

A Gatsby plugin which optimizes working with Gatsby Cloud

npm install gatsby-plugin-gatsby-cloud

README

gatsby-plugin-gatsby-cloud

Automatically generates a _headers.json file and a _redirects.json file at the root of the public folder to configure Headers and Redirects on Gatsby Cloud

By default, the plugin will add some basic security headers. You can easily add or replace headers through the plugin config.

Install

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

How to use

// In your gatsby-config.js
plugins: [`gatsby-plugin-gatsby-cloud`]

Configuration

If you just need the critical assets, you don't need to add any additional config. However, if you want to add headers, remove default headers, or transform the given headers, you can use the following configuration options.

plugins: [
  {
    resolve: `gatsby-plugin-gatsby-cloud`,
    options: {
      headers: {}, // option to add more headers. `Link` headers are transformed by the below criteria
      allPageHeaders: [], // option to add headers for all pages. `Link` headers are transformed by the below criteria
      mergeSecurityHeaders: true, // boolean to turn off the default security headers
      mergeLinkHeaders: true, // boolean to turn off the default gatsby js headers
      mergeCachingHeaders: true, // boolean to turn off the default caching headers
      transformHeaders: (headers, path) => headers, // optional transform for manipulating headers under each path (e.g.sorting), etc.
      generateMatchPathRewrites: true, // boolean to turn off automatic creation of redirect rules for client only paths
    },
  },
]

Headers

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

The _headers.json file does not inherit headers, and it will replace any matching headers it finds in more 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 put 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 path.

{
  options: {
    allPageHeaders: [
      "Link: </static/my-logo.png>; rel=preload; as=image",
    ],
    headers: {
      "/*": [
        "Basic-Auth: someuser:somepassword anotheruser:anotherpassword",
      ],
    },
  }
}

Redirects

You can create redirects using the createRedirect action.

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

Attribute Description
statusCode Overrides the HTTP status code which is set to 302 by default or 301 when isPermanent is true. You can set one here. For example, 200 for rewrites, or 404 for a custom error page.

An example:

createRedirect({ fromPath: "/old-url", toPath: "/new-url", isPermanent: true })
createRedirect({ fromPath: "/url", toPath: "/zn-CH/url", Language: "zn" })
createRedirect({
  fromPath: "/url_that_is/not_pretty",
  toPath: "/pretty/url",
  statusCode: 200,
})
createRedirect({
  fromPath: "/packages/*",
  toPath: "/plugins/*",
})

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.

An asterisk, *, will match anything that follows. i.e. /packages/gatsby-plugin-gatsby-cloud/ will be redirected to /plugins/gatsby-plugin-gatsby-cloud/.

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

General

License
MIT
Typescript Types
None found
Tree-shakeable
No

Popularity

GitHub Stargazers
53.6K
Community Interest
62.7K
Number of Forks
10.4K

Maintenance

Commits
10/219/220200
Last Commit
Open Issues
92
Closed Issues
13.5K
Open Pull Requests
156
Closed Pull Requests
3,510

Versions

Versions Released
10/219/22030
Latest Version Released
Aug 2, 2022
Current Tags
latest4.20.0
next4.21.0-next.1
v3rc2.0.0-v3rc.1
mdxv4-rc4.20.0-mdxv4-rc.124
alpha-ssr2.10.0-alpha-ssr.39
coreutils2.12.0-coreutils.29
image-cdn4.9.0-alpha-image-service2.14
latest-v33.2.1
logroutes2.12.0-logroutes.12
alpha-qe-sm3.2.0-alpha-qe-sm.2
drupal-next3.2.0-drupal-next.50
alpha-9689ff4.0.0-alpha-9689ff.13
alpha-mdx-v24.18.0-alpha-mdx-v2.68
alpha-ts-jit4.6.0-alpha-ts-jit.27
createroutes2.12.0-createroutes.30
gatsby-cloud4.5.0-alpha-gatsby-cloud.320
reach-router1.1.0-reach-router.13
stream-write2.10.0-stream-write.10
wildcardtest4.0.0-alpha-wildcard-test.5
gpgc-feedback4.6.0-alpha-gpgc-feedback.8
image-service4.8.0-alpha-image-service.26
wp-graphql-bug4.13.0-alpha-wp-graphql-bug.3
abhi-cloud-test2.6.0-abhi-cloud-test.406
assetprefixtest4.1.0-alpha-assetprefix-test.16
alpha-path-prefix2.12.0-alpha-path-prefix.1
alpha-remote-file2.10.0-alpha-remote-file.48
support-all-sites4.6.0-alpha-support-all-sites.29
wp-image-cdn-auth4.15.0-alpha-wp-image-cdn-auth.45
alpha-cloud-routes2.6.0-alpha-cloud-routes.417
alpha-remote-fetch3.2.0-alpha-remote-fetch.79
gatsby-plugin-cloud4.7.0-alpha-gatsby-plugin-cloud.42
alpha-trailing-slash4.5.0-alpha-trailing-slash.76
drupal-self-reference4.18.0-alpha-drupal-self-reference.18
gatsby-plugin-gatsby-cloud4.5.0-alpha-gatsby-plugin-gatsby-cloud.531
gatsby-plugin-gatsby-cloud.12.8.0-alpha-gatsby-plugin-gatsby-cloud.1.72
gatsby-plugin-gatsby-cloud.22.8.0-alpha-gatsby-plugin-gatsby-cloud.2.72
gatsby-plugin-gatsby-cloud.692.8.0-alpha-gatsby-plugin-gatsby-cloud.69.68

Contributors

KyleAMathews
KyleAMathews
Commits: 3,014
pieh
pieh
Commits: 884
wardpeet
wardpeet
Commits: 506
LekoArts
LekoArts
Commits: 436
sidharthachatterjee
sidharthachatterjee
Commits: 436
m-allanson
m-allanson
Commits: 354
DSchau
DSchau
Commits: 354
muescha
muescha
Commits: 301
vladar
vladar
Commits: 268
shannonbux
shannonbux
Commits: 268
pvdz
pvdz
Commits: 240
ascorbic
ascorbic
Commits: 240
fk
fk
Commits: 217
ChristopherBiscardi
ChristopherBiscardi
Commits: 186
tesseralis
tesseralis
Commits: 158