Skip to content

chore: update readme #59

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 19, 2022
Merged

chore: update readme #59

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
014207b
chore: update readme
ascorbic Jan 19, 2022
ce23cbb
Merge branch 'main' into mk/update-intro
ascorbic Jan 19, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 43 additions & 36 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,18 @@
# gatsby-plugin-netlify

Automatically generates a `_headers` file and a `_redirects` file at the root of the public folder to configure
[HTTP headers](https://www.netlify.com/docs/headers-and-basic-auth/) and [redirects](https://www.netlify.com/docs/redirects/) on Netlify.
This plugin adds support for Gatsby SSR and DSG on Netlify, and handles Gatsby redirects and headers.

By default, the plugin will add some basic security headers. You can easily add or replace headers through the plugin config.
The plugin works by automatically generating a `_headers` and `_redirects` file at the root of the public folder to
configure [HTTP headers](https://www.netlify.com/docs/headers-and-basic-auth/) and
[redirects](https://www.netlify.com/docs/redirects/) on Netlify.

**When not to use the plugin:** In case you just want to use a `_redirects` or `_headers` file for Netlify with Gatsby, you don't need this plugin. Instead, move those files in `/static/_redirects`, `/static/_headers` and Gatsby will copy them to your root folder during build where Netlify will pick them up.
By default, the plugin will add some basic security headers. You can easily add or replace headers through the plugin
config.

**When not to use the plugin:** In case you just want to use your own `_redirects` or `_headers` file for Netlify with
Gatsby, you don't need this plugin. Instead, move those files in `/static/_redirects`, `/static/_headers` and Gatsby
will copy them to your root folder during build where Netlify will pick them up. Note that this plugin is still required
if you want to use SSR or DSG rendering.

## Install

Expand All @@ -20,9 +27,8 @@ plugins: [`gatsby-plugin-netlify`]

## 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.
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: [
Expand All @@ -44,9 +50,8 @@ plugins: [
### Headers

The headers object represents a JS version of the
[Netlify `_headers` file format](https://www.netlify.com/docs/headers-and-basic-auth/).
You should pass in an object with string keys (representing the paths) and an
array of strings for each header.
[Netlify `_headers` file format](https://www.netlify.com/docs/headers-and-basic-auth/). You should pass in an object
with string keys (representing the paths) and an array of strings for each header.

An example:

Expand All @@ -66,13 +71,13 @@ An example:
}
```

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

When `mergeLinkHeaders` is true, as it is by default, this plugin will generate HTTP preload headers for the asset paths for all of your application's pages.
When `mergeLinkHeaders` is true, as it is by default, this plugin will generate HTTP preload headers for the asset paths
for all of your application's pages.

An example:

Expand All @@ -90,17 +95,15 @@ An example:

Therefore, expect the size of the `_headers` file to grow linearly with the number of pages in your application.

> **Note:** Gatsby also adds these preload tags in your pages' index.html files, whether or not you are using this plugin.
> **Note:** Gatsby also adds these preload tags in your pages' index.html files, whether or not you are using this
> plugin.

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.

The Netlify `_headers` 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.
The Netlify `_headers` 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.

```javascript
{
Expand All @@ -117,8 +120,7 @@ have to add to every path. To make this easier, the plugin provides the
}
```

You can validate the `_headers` config through the
[Netlify playground app](https://play.netlify.com/headers).
You can validate the `_headers` config through the [Netlify playground app](https://play.netlify.com/headers).

### Redirects

Expand All @@ -134,26 +136,31 @@ In addition to the options provided by the Gatsby API, you can pass these option
An example:

```javascript
createRedirect({ fromPath: "/old-url", toPath: "/new-url", isPermanent: true })
createRedirect({ fromPath: "/url", toPath: "/zn-CH/url", Language: "zn" })
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",
fromPath: '/url_that_is/not_pretty',
toPath: '/pretty/url',
statusCode: 200,
})
```

You can also create a `_redirects` file in the `static` folder for the same effect. Any programmatically created redirects will be appended to the file.
You can also create a `_redirects` file in the `static` folder for the same effect. Any programmatically created
redirects will be appended to the file.

```shell
# my manually set redirects
/home /
/blog/my-post.php /blog/my-post
```

You can validate the `_redirects` config through the
[Netlify playground app](https://play.netlify.com/redirects).
You can validate the `_redirects` config through the [Netlify playground app](https://play.netlify.com/redirects).

Redirect rules are automatically added for [client only paths](https://www.gatsbyjs.org/docs/client-only-routes-and-user-authentication). The plugin uses the [matchPath](https://www.gatsbyjs.org/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.org/docs/client-only-routes-and-user-authentication). The plugin uses the
[matchPath](https://www.gatsbyjs.org/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`.
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`.