|
| 1 | +# gatsby-plugin-netlify |
| 2 | + |
| 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. |
| 5 | + |
| 6 | +By default, the plugin will add some basic security headers. You can easily add or replace headers through the plugin config. |
| 7 | + |
| 8 | +## Install |
| 9 | + |
| 10 | +`npm install gatsby-plugin-netlify` |
| 11 | + |
| 12 | +## How to use |
| 13 | + |
| 14 | +```javascript |
| 15 | +// In your gatsby-config.js |
| 16 | +plugins: [`gatsby-plugin-netlify`] |
| 17 | +``` |
| 18 | + |
| 19 | +## Configuration |
| 20 | + |
| 21 | +If you just need the critical assets, you don't need to add any additional |
| 22 | +config. However, if you want to add headers, remove default headers, or |
| 23 | +transform the given headers, you can use the following configuration options. |
| 24 | + |
| 25 | +```javascript |
| 26 | +plugins: [ |
| 27 | + { |
| 28 | + resolve: `gatsby-plugin-netlify`, |
| 29 | + options: { |
| 30 | + headers: {}, // option to add more headers. `Link` headers are transformed by the below criteria |
| 31 | + allPageHeaders: [], // option to add headers for all pages. `Link` headers are transformed by the below criteria |
| 32 | + mergeSecurityHeaders: true, // boolean to turn off the default security headers |
| 33 | + mergeLinkHeaders: true, // boolean to turn off the default gatsby js headers |
| 34 | + mergeCachingHeaders: true, // boolean to turn off the default caching headers |
| 35 | + transformHeaders: (headers, path) => headers, // optional transform for manipulating headers under each path (e.g.sorting), etc. |
| 36 | + generateMatchPathRewrites: true, // boolean to turn off automatic creation of redirect rules for client only paths |
| 37 | + }, |
| 38 | + }, |
| 39 | +] |
| 40 | +``` |
| 41 | + |
| 42 | +### Headers |
| 43 | + |
| 44 | +The headers object represents a JS version of the |
| 45 | +[Netlify `_headers` file format](https://www.netlify.com/docs/headers-and-basic-auth/). |
| 46 | +You should pass in an object with string keys (representing the paths) and an |
| 47 | +array of strings for each header. |
| 48 | + |
| 49 | +An example: |
| 50 | + |
| 51 | +```javascript |
| 52 | +{ |
| 53 | + options: { |
| 54 | + headers: { |
| 55 | + "/*": [ |
| 56 | + "Basic-Auth: someuser:somepassword anotheruser:anotherpassword", |
| 57 | + ], |
| 58 | + "/my-page": [ |
| 59 | + // matching headers (by type) are replaced by Netlify with more specific routes |
| 60 | + "Basic-Auth: differentuser:differentpassword", |
| 61 | + ], |
| 62 | + }, |
| 63 | + } |
| 64 | +} |
| 65 | +``` |
| 66 | + |
| 67 | +Link paths are specially handled by this plugin. Since most files are processed |
| 68 | +and cache-busted through Gatsby (with a file hash), the plugin will transform |
| 69 | +any base file names to the hashed variants. If the file is not hashed, it will |
| 70 | +ensure the path is valid relative to the output `public` folder. You should be |
| 71 | +able to reference assets imported through javascript in the `static` folder. |
| 72 | + |
| 73 | +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. |
| 74 | + |
| 75 | +An example: |
| 76 | + |
| 77 | +``` |
| 78 | +/my-page |
| 79 | + Link: </webpack-runtime-61d3e010ac286a1ce7e1.js>; rel=preload; as=script |
| 80 | + Link: </styles-89fd2ae28bdf06750a71.js>; rel=preload; as=script |
| 81 | + Link: </framework-376edee25eb5f5cd8260.js>; rel=preload; as=script |
| 82 | + Link: </app-9035e07a2b55474b8eee.js>; rel=preload; as=script |
| 83 | + Link: </styles-89fd2ae28bdf06750a71.js>; rel=preload; as=script |
| 84 | + Link: </component---src-pages-index-js-102db70fdea806a1e5b8.js>; rel=preload; as=script |
| 85 | + Link: </page-data/app-data.json>; rel=preload; as=fetch; crossorigin |
| 86 | + Link: </page-data/index/page-data.json>; rel=preload; as=fetch; crossorigin |
| 87 | +``` |
| 88 | + |
| 89 | +Therefore, expect the size of the `_headers` file to grow linearly with the number of pages in your application. |
| 90 | + |
| 91 | +> **Note:** Gatsby also adds these preload tags in your pages' index.html files, whether or not you are using this plugin. |
| 92 | +
|
| 93 | +Do not specify the public path in the config, as the plugin will provide it for |
| 94 | +you. |
| 95 | + |
| 96 | +The Netlify `_headers` file does not inherit headers, and it will replace any |
| 97 | +matching headers it finds in more specific routes. For example, if you add a |
| 98 | +link to the root wildcard path (`/*`), it will be replaced by any more |
| 99 | +specific path. If you want a resource to put linked across the site, you will |
| 100 | +have to add to every path. To make this easier, the plugin provides the |
| 101 | +`allPageHeaders` option to inject the same headers on every path. |
| 102 | + |
| 103 | +```javascript |
| 104 | +{ |
| 105 | + options: { |
| 106 | + allPageHeaders: [ |
| 107 | + "Link: </static/my-logo.png>; rel=preload; as=image", |
| 108 | + ], |
| 109 | + headers: { |
| 110 | + "/*": [ |
| 111 | + "Basic-Auth: someuser:somepassword anotheruser:anotherpassword", |
| 112 | + ], |
| 113 | + }, |
| 114 | + } |
| 115 | +} |
| 116 | +``` |
| 117 | + |
| 118 | +You can validate the `_headers` config through the |
| 119 | +[Netlify playground app](https://play.netlify.com/headers). |
| 120 | + |
| 121 | +### Redirects |
| 122 | + |
| 123 | +You can create redirects using the [`createRedirect`](https://www.gatsbyjs.org/docs/actions/#createRedirect) action. |
| 124 | + |
| 125 | +In addition to the options provided by the Gatsby API, you can pass these options specific to this plugin: |
| 126 | + |
| 127 | +| Attribute | Description | |
| 128 | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 129 | +| `force` | Overrides existing content in the path. This is particularly useful for domain alias redirects. See [the Netlify documentation for this option](https://www.netlify.com/docs/redirects/#structured-configuration). | |
| 130 | +| `statusCode` | Overrides the HTTP status code which is set to `302` by default or `301` when [`isPermanent`](https://www.gatsbyjs.org/docs/actions/#createRedirect) is `true`. Since Netlify supports custom status codes, you can set one here. For example, `200` for rewrites, or `404` for a custom error page. See [the Netlify documentation for this option](https://www.netlify.com/docs/redirects/#http-status-codes). | |
| 131 | + |
| 132 | +An example: |
| 133 | + |
| 134 | +```javascript |
| 135 | +createRedirect({ fromPath: "/old-url", toPath: "/new-url", isPermanent: true }) |
| 136 | +createRedirect({ fromPath: "/url", toPath: "/zn-CH/url", Language: "zn" }) |
| 137 | +createRedirect({ |
| 138 | + fromPath: "/url_that_is/not_pretty", |
| 139 | + toPath: "/pretty/url", |
| 140 | + statusCode: 200, |
| 141 | +}) |
| 142 | +``` |
| 143 | + |
| 144 | +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. |
| 145 | + |
| 146 | +```shell |
| 147 | +# my manually set redirects |
| 148 | +/home / |
| 149 | +/blog/my-post.php /blog/my-post |
| 150 | +``` |
| 151 | + |
| 152 | +You can validate the `_redirects` config through the |
| 153 | +[Netlify playground app](https://play.netlify.com/redirects). |
| 154 | + |
| 155 | +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. |
| 156 | + |
| 157 | +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`. |
0 commit comments