Community Plugin

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:

Getting Started

Install the package with npm or yarn

npm install gatsby-plugin-htaccess

yarn add gatsby-plugin-htaccess
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.