Skip to content

Commit 140a71d

Browse files
ascorbicascorbic
authored
chore: update readme (#59)
Release-As: 4.0.0
1 parent 4ab7222 commit 140a71d

File tree

1 file changed

+43
-36
lines changed

1 file changed

+43
-36
lines changed

‎README.md

Lines changed: 43 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,18 @@
11
# gatsby-plugin-netlify
22

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

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

8-
**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.
9+
By default, the plugin will add some basic security headers. You can easily add or replace headers through the plugin
10+
config.
11+
12+
**When not to use the plugin:** In case you just want to use your own `_redirects` or `_headers` file for Netlify with
13+
Gatsby, you don't need this plugin. Instead, move those files in `/static/_redirects`, `/static/_headers` and Gatsby
14+
will copy them to your root folder during build where Netlify will pick them up. Note that this plugin is still required
15+
if you want to use SSR or DSG rendering.
916

1017
## Install
1118

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

2128
## Configuration
2229

23-
If you just need the critical assets, you don't need to add any additional
24-
config. However, if you want to add headers, remove default headers, or
25-
transform the given headers, you can use the following configuration options.
30+
If you just need the critical assets, you don't need to add any additional config. However, if you want to add headers,
31+
remove default headers, or transform the given headers, you can use the following configuration options.
2632

2733
```javascript
2834
plugins: [
@@ -44,9 +50,8 @@ plugins: [
4450
### Headers
4551

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

5156
An example:
5257

@@ -66,13 +71,13 @@ An example:
6671
}
6772
```
6873

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

75-
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.
79+
When `mergeLinkHeaders` is true, as it is by default, this plugin will generate HTTP preload headers for the asset paths
80+
for all of your application's pages.
7681

7782
An example:
7883

@@ -90,17 +95,15 @@ An example:
9095

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

93-
> **Note:** Gatsby also adds these preload tags in your pages' index.html files, whether or not you are using this plugin.
98+
> **Note:** Gatsby also adds these preload tags in your pages' index.html files, whether or not you are using this
99+
> plugin.
94100
95-
Do not specify the public path in the config, as the plugin will provide it for
96-
you.
101+
Do not specify the public path in the config, as the plugin will provide it for you.
97102

98-
The Netlify `_headers` file does not inherit headers, and it will replace any
99-
matching headers it finds in more specific routes. For example, if you add a
100-
link to the root wildcard path (`/*`), it will be replaced by any more
101-
specific path. If you want a resource to put linked across the site, you will
102-
have to add to every path. To make this easier, the plugin provides the
103-
`allPageHeaders` option to inject the same headers on every path.
103+
The Netlify `_headers` file does not inherit headers, and it will replace any matching headers it finds in more specific
104+
routes. For example, if you add a link to the root wildcard path (`/*`), it will be replaced by any more specific path.
105+
If you want a resource to put linked across the site, you will have to add to every path. To make this easier, the
106+
plugin provides the `allPageHeaders` option to inject the same headers on every path.
104107

105108
```javascript
106109
{
@@ -117,8 +120,7 @@ have to add to every path. To make this easier, the plugin provides the
117120
}
118121
```
119122

120-
You can validate the `_headers` config through the
121-
[Netlify playground app](https://play.netlify.com/headers).
123+
You can validate the `_headers` config through the [Netlify playground app](https://play.netlify.com/headers).
122124

123125
### Redirects
124126

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

136138
```javascript
137-
createRedirect({ fromPath: "/old-url", toPath: "/new-url", isPermanent: true })
138-
createRedirect({ fromPath: "/url", toPath: "/zn-CH/url", Language: "zn" })
139+
createRedirect({ fromPath: '/old-url', toPath: '/new-url', isPermanent: true })
140+
createRedirect({ fromPath: '/url', toPath: '/zn-CH/url', Language: 'zn' })
139141
createRedirect({
140-
fromPath: "/url_that_is/not_pretty",
141-
toPath: "/pretty/url",
142+
fromPath: '/url_that_is/not_pretty',
143+
toPath: '/pretty/url',
142144
statusCode: 200,
143145
})
144146
```
145147

146-
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.
148+
You can also create a `_redirects` file in the `static` folder for the same effect. Any programmatically created
149+
redirects will be appended to the file.
147150

148151
```shell
149152
# my manually set redirects
150153
/home /
151154
/blog/my-post.php /blog/my-post
152155
```
153156

154-
You can validate the `_redirects` config through the
155-
[Netlify playground app](https://play.netlify.com/redirects).
157+
You can validate the `_redirects` config through the [Netlify playground app](https://play.netlify.com/redirects).
156158

157-
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.
159+
Redirect rules are automatically added for
160+
[client only paths](https://www.gatsbyjs.org/docs/client-only-routes-and-user-authentication). The plugin uses the
161+
[matchPath](https://www.gatsbyjs.org/docs/gatsby-internals-terminology/#matchpath) syntax to match all possible requests
162+
in the range of your client-side routes and serves the HTML file for the client-side route. Without it, only the exact
163+
route of the client-side route works.
158164

159-
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`.
165+
If those rules are conflicting with custom rules or if you want to have more control over them you can disable them in
166+
[configuration](#configuration) by setting `generateMatchPathRewrites` to `false`.

0 commit comments

Comments
 (0)