94 lines
5.5 KiB
Markdown
94 lines
5.5 KiB
Markdown
|
# 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:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
astro add astro-htaccess
|
||
|
|
```
|
||
|
|
|
||
|
|
Or to install it manually, first run:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
npm install --save astro-htaccess@latest
|
||
|
|
```
|
||
|
|
|
||
|
|
Then add it to your astro configuration (i.e. `astro.config.mjs`):
|
||
|
|
|
||
|
|
```diff
|
||
|
|
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](https://httpd.apache.org/docs/2.2/mod/mod_alias.html#redirectmatch), 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](https://docs.astro.build/en/guides/environment-variables/) with Astro's [experimental `astro:env` API](https://docs.astro.build/en/reference/configuration-reference/#experimentalenv) 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.
|
||
|
|
|
||
|
|
```js
|
||
|
|
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:
|
||
|
|
|
||
|
|
```txt
|
||
|
|
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
|
||
|
|
```
|