Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub

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

  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'],


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!


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.


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

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

© 2023 Gatsby, Inc.