{"id":19982415,"url":"https://github.com/netlify/gatsby-plugin-netlify","last_synced_at":"2025-04-05T23:12:15.952Z","repository":{"id":37959165,"uuid":"377088289","full_name":"netlify/gatsby-plugin-netlify","owner":"netlify","description":"Gatsby plugin. Automatically generates a _headers file and a _redirects file at the root of the public folder to configure HTTP headers and redirects on Netlify.","archived":false,"fork":false,"pushed_at":"2025-03-31T00:41:32.000Z","size":4194,"stargazers_count":13,"open_issues_count":12,"forks_count":11,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-02T23:06:55.363Z","etag":null,"topics":["production"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/netlify.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-15T08:18:35.000Z","updated_at":"2025-03-31T00:40:39.000Z","dependencies_parsed_at":"2023-11-13T02:28:39.546Z","dependency_job_id":"150f8e4a-9e62-452f-abb6-e6a6de156e45","html_url":"https://github.com/netlify/gatsby-plugin-netlify","commit_stats":{"total_commits":216,"total_committers":18,"mean_commits":12.0,"dds":"0.40740740740740744","last_synced_commit":"86d6704fc97a53c0d57c475c63a6c7938afd855e"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netlify%2Fgatsby-plugin-netlify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netlify%2Fgatsby-plugin-netlify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netlify%2Fgatsby-plugin-netlify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netlify%2Fgatsby-plugin-netlify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/netlify","download_url":"https://codeload.github.com/netlify/gatsby-plugin-netlify/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247411239,"owners_count":20934653,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["production"],"created_at":"2024-11-13T04:11:12.043Z","updated_at":"2025-04-05T23:12:15.917Z","avatar_url":"https://github.com/netlify.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gatsby-plugin-netlify\n\nThis plugin adds support for Gatsby SSR and DSG on Netlify, and handles Gatsby redirects and headers.\n\nThe plugin works by automatically generating a `_headers` and `_redirects` file at the root of the public folder to\nconfigure [HTTP headers](https://www.netlify.com/docs/headers-and-basic-auth/) and\n[redirects](https://www.netlify.com/docs/redirects/) on Netlify.\n\nBy default, the plugin will add some basic security headers. You can easily add or replace headers through the plugin\nconfig.\n\n**When not to use the plugin:** In case you just want to use your own `_redirects` or `_headers` file for Netlify with\nGatsby, you don't need this plugin. Instead, move those files in `/static/_redirects`, `/static/_headers` and Gatsby\nwill copy them to your root folder during build where Netlify will pick them up. Note that this plugin is still required\nif you want to use SSR or DSG rendering.\n\n## Install\n\n```shell\nnpm install gatsby-plugin-netlify\n```\n\n## How to use\n\nAdd `gatsby-plugin-netlify` to your `gatsby-config`:\n\n```js:title=gatsby-config.js\nmodule.exports = {\n  plugins: [`gatsby-plugin-netlify`]\n}\n```\n\n## Configuration\n\nIf you just need the critical assets, you don't need to add any additional config. However, if you want to add headers,\nremove default headers, or transform the given headers, you can use the following configuration options:\n\n```js:title=gatsby-config.js\nmodule.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-plugin-netlify`,\n      options: {\n        headers: {}, // option to add more headers. `Link` headers are transformed by the below criteria\n        allPageHeaders: [], // option to add headers for all pages. `Link` headers are transformed by the below criteria\n        mergeSecurityHeaders: true, // boolean to turn off the default security headers\n        mergeCachingHeaders: true, // boolean to turn off the default caching headers\n        transformHeaders: (headers, path) =\u003e headers, // optional transform for manipulating headers under each path (e.g.sorting), etc.\n        generateMatchPathRewrites: true, // boolean to turn off automatic creation of redirect rules for client only paths\n      },\n    },\n  ]\n}\n```\n\n### Headers\n\nThe headers object represents a JS version of the\n[Netlify `_headers` file format](https://www.netlify.com/docs/headers-and-basic-auth/). You should pass in an object\nwith string keys (representing the paths) and an array of strings for each header.\n\nAn example:\n\n```javascript\n{\n  options: {\n    headers: {\n      \"/*\": [\n        \"Basic-Auth: someuser:somepassword anotheruser:anotherpassword\",\n      ],\n      \"/my-page\": [\n        // matching headers (by type) are replaced by Netlify with more specific routes\n        \"Basic-Auth: differentuser:differentpassword\",\n      ],\n    },\n  }\n}\n```\n\nLink paths are specially handled by this plugin. Since most files are processed and cache-busted through Gatsby (with a\nfile hash), the plugin will transform any base file names to the hashed variants. If the file is not hashed, it will\nensure the path is valid relative to the output `public` folder. You should be able to reference assets imported through\njavascript in the `static` folder.\n\nDo not specify the public path in the config, as the plugin will provide it for you.\n\nThe Netlify `_headers` file does not inherit headers, and it will replace any matching headers it finds in more specific\nroutes. For example, if you add a link to the root wildcard path (`/*`), it will be replaced by any more specific path.\nIf you want a resource to put linked across the site, you will have to add to every path. To make this easier, the\nplugin provides the `allPageHeaders` option to inject the same headers on every path.\n\n```javascript\n{\n  options: {\n    allPageHeaders: [\n      \"Link: \u003c/static/my-logo.png\u003e; rel=preload; as=image\",\n    ],\n    headers: {\n      \"/*\": [\n        \"Basic-Auth: someuser:somepassword anotheruser:anotherpassword\",\n      ],\n    },\n  }\n}\n```\n\nYou can validate the `_headers` config through the [Netlify playground app](https://play.netlify.com/headers).\n\n### Redirects\n\nYou can create redirects using the\n[`createRedirect`](https://www.gatsbyjs.com/docs/reference/config-files/actions/#createRedirect) action.\n\nIn addition to the options provided by the Gatsby API, you can pass these options specific to this plugin:\n\n| Attribute    | Description                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `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).                                                                                                                                                                                                                      |\n| `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`. 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). |\n\nAn example:\n\n```js:title=gatsby-node.js\nexports.createPages = ({ actions }) =\u003e {\n  const { createRedirect } = actions\n\n  createRedirect({ fromPath: '/old-url', toPath: '/new-url', isPermanent: true })\n  createRedirect({ fromPath: '/url', toPath: '/zn-CH/url', Language: 'zn' })\n  createRedirect({\n    fromPath: '/url_that_is/not_pretty',\n    toPath: '/pretty/url',\n    statusCode: 200,\n  })\n}\n```\n\nYou can also create a `_redirects` file in the `static` folder for the same effect. Any programmatically created\nredirects will be appended to the file.\n\n```shell\n# my manually set redirects\n/home              /\n/blog/my-post.php  /blog/my-post\n```\n\nYou can validate the `_redirects` config through the [Netlify playground app](https://play.netlify.com/redirects).\n\nRedirect rules are automatically added for\n[client only paths](https://www.gatsbyjs.com/docs/how-to/routing/client-only-routes-and-user-authentication/). The\nplugin uses the [matchPath](https://www.gatsbyjs.com/docs/gatsby-internals-terminology/#matchpath) syntax to match all\npossible requests in the range of your client-side routes and serves the HTML file for the client-side route. Without\nit, only the exact route of the client-side route works.\n\nIf those rules are conflicting with custom rules or if you want to have more control over them you can disable them in\n[configuration](#configuration) by setting `generateMatchPathRewrites` to `false`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetlify%2Fgatsby-plugin-netlify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetlify%2Fgatsby-plugin-netlify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetlify%2Fgatsby-plugin-netlify/lists"}