Gatsby Plugin Htaccess

Gatsby Plugin Htaccess creates a “.htaccess”-file every time a gatsby build is triggered. This file contains by default all basic rules specified by Apache Server Configs v2.4.0.

Additionally, the headers for HTTP caching are set as recommended by the Gatsby team: https://www.gatsbyjs.org/docs/caching/

Default output

Without any configuration the plugin will output these files:

• /public/.htaccess
• /public/static/.htaccess

Getting Started

1. Install the package with npm or yarn

   npm install gatsby-plugin-htaccess

   yarn add gatsby-plugin-htaccess

2. Add to plugins in your gatsby-config.js

module.exports = {
  plugins: ['gatsby-plugin-htaccess'],
}

Options

| Name | Type | Description | | :------------------- | :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | RewriteBase | bool or string | Set to true, it will output RewriteBase /. You can also define a custom RewriteBase. | | https | bool | Force https. | | www | bool | Suppress/force “www” at the beginning of URLs. By default "www" is supressed. | | DisallowSymLinks | bool | By default Options +FollowSymlinks is activated. If your hoster does not allow this option, you can set DisallowSymLinks to true. | | SymLinksIfOwnerMatch | bool | You can restrict follow symlinks to owner match. | | host | string | Defines the domain, every other domain, that leads to your website, gets redirected to. Like Redirecting Domains from redirects, but without having to define the alternate hosts. | | ErrorDocument | string | Define custom ErrorDocuments. Default: ErrorDocument 404 /404/index.html | | redirect | array of objects and/or strings | Fully customized redirects: Can be defined as strings. Redirecting Domains: If there are several domains pointing to your site, you can redirect them to your main domain by setting up objects with the keys from and to. Redirects from Gatsby: Redirects from Gatsby are not automatically integrated. If you just want that, you should generally go with gatsby-plugin-htaccess-redirects. | | custom | string | Custom Rules are added at the end of the file public/.htaccess. |

Example Options:

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-htaccess',
      options: {
        RewriteBase: '/custom/',
        https: true,
        www: true,
        SymLinksIfOwnerMatch: true,
        host: 'www.mydomain.com', // if 'www' is set to 'false', be sure to also remove it here!
        ErrorDocument: `
          ErrorDocument 401 /error_pages/401.html
          ErrorDocument 404 /error_pages/404.html
          ErrorDocument 500 /error_pages/500.html
        `,
        redirect: [
          'RewriteRule ^not-existing-url/?$ /existing-url [R=301,L,NE]',
          {
            from: 'my-domain.com',
            to: 'mydomain.com',
          },
          {
            from: 'my-other-domain.com',
            to: 'mydomain.com',
          },
        ],
        custom: `
            # This is a custom rule!
            # This is a another custom rule!
        `,
      },
    },
  ],
}

Contributing

Every contribution is very much appreciated. Feel free to file bugs, feature- and pull-requests.

If this plugin is helpful for you, star it on GitHub.

Thanks

This plugin is based on gatsby-plugin-htaccess-redirects by Gatsby Central.

The htaccess-directives are taken from Apache Server Configs by H5BP.