Skip to content

Commit

Permalink
chore(gatsby-plugin-gatsby-cloud): Update README (#37243)
Browse files Browse the repository at this point in the history
  • Loading branch information
@LekoArts
LekoArts committed Dec 13, 2022
1 parent 91d21a6 commit 33bc518
Showing 1 changed file with 96 additions and 77 deletions.
173 changes: 96 additions & 77 deletions packages/gatsby-plugin-gatsby-cloud/README.md
View file
@@ -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
Expand All @@ -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
Expand All @@ -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: </static/my-logo.png>; 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: </static/my-logo.png>; 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`.

Expand All @@ -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",
],
}
},
]
}
```

0 comments on commit 33bc518

Please sign in to comment.