From 33bc518f7321243240d7c2156b9d1e10e7fbc027 Mon Sep 17 00:00:00 2001 From: Lennart Date: Tue, 13 Dec 2022 12:01:24 +0100 Subject: [PATCH] chore(gatsby-plugin-gatsby-cloud): Update README (#37243) --- packages/gatsby-plugin-gatsby-cloud/README.md | 173 ++++++++++-------- 1 file changed, 96 insertions(+), 77 deletions(-) diff --git a/packages/gatsby-plugin-gatsby-cloud/README.md b/packages/gatsby-plugin-gatsby-cloud/README.md index 779570b743a32..d1e2d0359c49b 100644 --- a/packages/gatsby-plugin-gatsby-cloud/README.md +++ b/packages/gatsby-plugin-gatsby-cloud/README.md @@ -1,44 +1,49 @@ # 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. +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. +By default, the plugin will add some basic security headers. You can add or replace headers through the plugin config. -NOTE: This plugin is autoinstalled on Gatsby Cloud to ensure the latest compatible version, there is no need to install it locally unless you wish to add plugin config. +**Please note:** This plugin is autoinstalled on Gatsby Cloud to ensure the latest compatible version, there is no need to install it locally unless you wish to add plugin config. ## Install -`npm install --save gatsby-plugin-gatsby-cloud` +```shell +npm install gatsby-plugin-gatsby-cloud +``` ## How to use -```javascript -// In your gatsby-config.js -plugins: [`gatsby-plugin-gatsby-cloud`] +```js:title=gatsby-config.js +module.exports = { + 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. - -```javascript -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 +transform the given headers, you can use the following configuration options: + +```js:title=gatsby-config.js +module.exports = { + 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 @@ -48,30 +53,30 @@ array of strings for each header. An example: -```javascript -{ - 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", - ], +```js:title=gatsby-config.js +module.exports = { + plugins: [ + { + resolve: `gatsby-plugin-gatsby-cloud`, + 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. +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. -Do not specify the public path in the config, as the plugin will provide it for -you. +If you want to preload files that you import through webpack in your application (e.g. somewhere in `src`), use the `setHeadComponents` API like shown in [Preload your fonts](/docs/how-to/styling/using-local-fonts/#preload-your-fonts). 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 @@ -80,48 +85,57 @@ 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. -```javascript -{ - options: { - allPageHeaders: [ - "Link: ; rel=preload; as=image", - ], - headers: { - "/*": [ - "Basic-Auth: someuser:somepassword anotheruser:anotherpassword", - ], +```js:title=gatsby-config.js +module.exports = { + plugins: [ + { + resolve: `gatsby-plugin-gatsby-cloud`, + options: { + allPageHeaders: [ + "Link: ; rel=preload; as=image", + ], + headers: { + "/*": [ + "Basic-Auth: someuser:somepassword anotheruser:anotherpassword", + ], + }, + } }, - } + ] } ``` ### Redirects -You can create redirects using the [`createRedirect`](https://www.gatsbyjs.com/docs/actions/#createRedirect) action. +You can create redirects using the [`createRedirect`](https://www.gatsbyjs.com/docs/reference/config-files/actions/#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`](https://www.gatsbyjs.com/docs/actions/#createRedirect) is `true`. You can set one here. For example, `200` for rewrites, or `404` for a custom error page. | +| Attribute | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `statusCode` | Overrides the HTTP status code which is set to `302` by default or `301` when [`isPermanent`](https://www.gatsbyjs.com/docs/reference/config-files/actions/#createRedirect) is `true`. You can set one here. For example, `200` for rewrites, or `404` for a custom error page. | An example: -```javascript -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/*", -}) +```js:title=gatsby-node.js +exports.createPages = ({ actions }) => { + const { createRedirect } = actions + + 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](https://www.gatsbyjs.com/docs/client-only-routes-and-user-authentication). The plugin uses the [matchPath](https://www.gatsbyjs.com/docs/gatsby-internals-terminology/#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. +Redirect rules are automatically added for [client only paths](https://www.gatsbyjs.com/docs/how-to/routing/client-only-routes-and-user-authentication/). The plugin uses the [matchPath](https://www.gatsbyjs.com/docs/gatsby-internals-terminology/#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](#configuration) by setting `generateMatchPathRewrites` to `false`. @@ -133,12 +147,17 @@ An asterisk, `*`, will match anything that follows. i.e. `/packages/gatsby-plugi 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. -```javascript -{ - options: { - allPageHeaders: [ - "Strict-Transport-Security: max-age=31536000; includeSubDomains; preload", - ], - } +```js:title=gatsby-config.js +module.exports = { + plugins: [ + { + resolve: `gatsby-plugin-gatsby-cloud`, + options: { + allPageHeaders: [ + "Strict-Transport-Security: max-age=31536000; includeSubDomains; preload", + ], + } + }, + ] } ```