astro-htaccess

SSG-only integration for Astro 4+ to generate an Apache .htaccess file, from user-defined rules and Astro's configuration.

Installation

To automatically install the integration with the default configuration:

astro add astro-htaccess

Or to install it manually, first run:

npm install --save astro-htaccess@latest

Then add it to your astro configuration (i.e. astro.config.mjs):

import { defineConfig } from 'astro/config';
+import htaccessIntegration from "astro-htaccess";

export default defineConfig({
-  integrations: [],
+  integrations: [htaccessIntegration()],
})

Configuration

The following properties can be passed to an object when calling htaccessIntegration():

Option	Description
generateHtaccessFile	a boolean, or function that returns a boolean or a Promise<boolean>. If false, then no files will not be generated; if true or omitted, then .htaccess will be created at the root of the output directory.
errorPages	List of custom error pages to generate for user-specified HTTP errors. If omitted, astro-htaccess will generate these for you based on any src/content/*.astro routes that match a valid HTTP error.
redirects	List of custom redirects to add as RedirectMatch rules, on top of the redirects defined in the redirects property of your Astro config. You can use Javascript regular expressions as the matcher, or a plain string for finer control over the output expression; and you can specify a custom redirect code for each rule (default is 301).
customRules	Custom rules to add to the output .htaccess file directly.

Example configuration

Here, we are using an environment variable with Astro's experimental astro:env API to decide whether to generate our configuration file. We use a custom error in src/content/errors/404.astro (but we could've simply placed it at src/content/404.astro and removed the errorPages field to automatically detect it). Then, we specify two outward-bound redirects on top of Astro's redirect, and finally, we add some custom rules to enforce HTTP authentication for the whole site.

import { defineConfig, envField } from "astro/config";
import htaccessIntegration from "astro-htaccess";

// https://astro.build/config
export default defineConfig({
  site: "https://example.astro.build/",
  integrations: [
    htaccessIntegration({
      generateHtaccessFile: import.meta.env.GENERATE_HTACCESS_FILE === "true",
      errorPages: [{ code: 404, document: "/errors/404" }],
      redirects: [
        { match: /^\/package@npm$/, url: "https://www.npmjs.com/package/astro-htaccess" },
        { match: "^/github\\b", url: "https://github.com/BadMannersXYZ/astro-htaccess", code: 302 },
      ],
      customRules: [
        `AuthType Basic`,
        `AuthName "Protected website"`,
        `AuthUserFile ../private/.htpasswd`,
        `require valid-user`,
      ],
    }),
  ],
  redirects: {
    "/faq": "/about_this_project",
  },
  experimental: {
    env: {
      schema: {
        GENERATE_HTACCESS_FILE: envField.boolean({ context: "server", access: "private", default: false }),
      },
    },
  },
});

In this example, when the GENERATE_HTACCESS_FILE environment variable is true, a .htaccess file containing the following rules is generated to our output directory:

AuthType Basic
AuthName "Protected website"
AuthUserFile ../private/.htpasswd
require valid-user
ErrorDocument 404 /errors/404.html
RedirectMatch 301 ^/faq(/(index.html)?)?$ /about_this_project
RedirectMatch 301 ^/package@npm$ https://www.npmjs.com/package/astro-htaccess
RedirectMatch 302 ^/github\b https://github.com/BadMannersXYZ/astro-htaccess