@flyewi/eleventy-plugin-redirects 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 flyewi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# eleventy-plugin-redirects
+
+[![Buy me a coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/flyewiy)
+
+Eleventy plugin that turns a single, centrally maintained redirects config into the formats your host actually understands: a Netlify `_redirects` file, an Apache `.htaccess`, and/or static HTML fallback pages for hosts that support neither.
+
+## Why
+
+URLs change. Instead of hand-editing `_redirects` (or forgetting to), keep redirects in your Eleventy config next to the rest of your site and let this plugin regenerate the host-specific file on every build.
+
+## Installation
+
+```
+npm install @flyewi/eleventy-plugin-redirects
+```
+
+```js
+const redirectsPlugin = require("@flyewi/eleventy-plugin-redirects");
+
+module.exports = function (eleventyConfig) {
+  eleventyConfig.addPlugin(redirectsPlugin, {
+    redirects: {
+      "/old-path/": "/new-path/",
+      "/legacy-page/": { to: "/new-page/", status: 302 },
+    },
+  });
+};
+```
+
+By default this writes an `_redirects` file into your output directory after every build.
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `redirects` | `{}` | Object map (`{ from: to }` or `{ from: { to, status } }`) or array of `{ from, to, status }`. Use the array form if the same `from` needs multiple rules. |
+| `defaultStatus` | `301` | Status code used when an entry doesn't specify one. |
+| `netlify` | `true` | Write a Netlify `_redirects` file. |
+| `netlifyFile` | `"_redirects"` | Filename for the Netlify output, relative to the output directory. |
+| `apache` | `false` | Write an Apache `.htaccess` with `Redirect` directives. |
+| `apacheFile` | `".htaccess"` | Filename for the Apache output. |
+| `html` | `false` | Also write a static HTML fallback page at each `from` URL (meta-refresh + `rel=canonical`), for hosts (e.g. GitHub Pages) that can't act on `_redirects`/`.htaccess`. |
+| `log` | `true` | Log a one-line summary after each build. |
+
+## Netlify output
+
+```
+/old-path/  /new-path/  301
+/legacy-page/  /new-page/  302
+```
+
+If your output directory already contains an `_redirects` file (e.g. copied through as a static passthrough for rules this plugin doesn't manage, like an SPA catch-all), the generated rules are **prepended** to it — Netlify uses the first matching rule, so your specific redirects still take priority over any broader existing rule.
+
+## Apache output
+
+```
+Redirect 301 /old-path/ /new-path/
+Redirect 302 /legacy-page/ /new-page/
+```
+
+## HTML fallback pages
+
+With `html: true`, each `from` path also gets a real HTML file at that URL (e.g. `/old-path/` → `old-path/index.html` in the output directory) containing:
+
+```html
+<meta http-equiv="refresh" content="0; url=/new-path/">
+<link rel="canonical" href="/new-path/">
+```
+
+This is a static fallback for platforms without server-side redirect support — a real `_redirects`/`.htaccess` (or your host/CDN's redirect rules) is always the better option when available, since the HTML approach is a moment slower and depends on the browser executing the refresh.
+
+## License
+
+MIT

package/lib/formats.js

@@ -0,0 +1,49 @@
+const path = require("node:path");
+
+function toNetlify(list) {
+  return list.map(({ from, to, status }) => `${from}  ${to}  ${status}`).join("\n") + "\n";
+}
+
+function toApache(list) {
+  return list.map(({ from, to, status }) => `Redirect ${status} ${from} ${to}`).join("\n") + "\n";
+}
+
+function escapeAttr(str) {
+  return String(str)
+    .replace(/&/g, "&")
+    .replace(/"/g, """)
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+// A static fallback for hosts that can't act on _redirects/.htaccess (e.g.
+// GitHub Pages): an actual HTML file at the old URL that both redirects
+// browsers instantly and points crawlers at the new canonical URL.
+function toHtmlPage(to) {
+  const target = escapeAttr(to);
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Redirecting…</title>
+<meta http-equiv="refresh" content="0; url=${target}">
+<link rel="canonical" href="${target}">
+</head>
+<body>
+<p>This page has moved to <a href="${target}">${target}</a>.</p>
+</body>
+</html>
+`;
+}
+
+// Maps a redirect's `from` path to the file Eleventy's pretty-URL convention
+// would expect it at, e.g. "/old-path" -> "old-path/index.html", so an HTML
+// fallback page lands exactly where the old URL is requested from.
+function toOutputPath(from) {
+  const clean = from.replace(/^\/+/, "");
+  if (clean === "" || clean.endsWith("/")) return path.join(clean, "index.html");
+  if (path.extname(clean)) return clean;
+  return path.join(clean, "index.html");
+}
+
+module.exports = { toNetlify, toApache, toHtmlPage, toOutputPath };

package/lib/normalize.js

@@ -0,0 +1,43 @@
+function normalizePath(p) {
+  return p.startsWith("/") ? p : `/${p}`;
+}
+
+// Accepts redirects as either an object map ({ "/old/": "/new/" } or
+// { "/old/": { to: "/new/", status: 302 } }) or an array of
+// { from, to, status } entries, and returns a single normalized array.
+// Object form is more convenient for hand-written config; array form allows
+// duplicate `from` paths (e.g. generated redirects) that an object key can't.
+function normalizeRedirects(redirects, defaultStatus) {
+  const list = [];
+
+  const addEntry = (from, to, status) => {
+    if (!from || !to) {
+      throw new Error(
+        `eleventy-plugin-redirects: invalid redirect entry (from: "${from}", to: "${to}")`
+      );
+    }
+    list.push({
+      from: normalizePath(from),
+      to,
+      status: status || defaultStatus,
+    });
+  };
+
+  if (Array.isArray(redirects)) {
+    for (const entry of redirects) {
+      addEntry(entry.from, entry.to, entry.status);
+    }
+  } else if (redirects && typeof redirects === "object") {
+    for (const [from, value] of Object.entries(redirects)) {
+      if (typeof value === "string") {
+        addEntry(from, value);
+      } else if (value && typeof value === "object") {
+        addEntry(from, value.to, value.status);
+      }
+    }
+  }
+
+  return list;
+}
+
+module.exports = { normalizeRedirects, normalizePath };

package/lib/redirects.js

@@ -0,0 +1,74 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+const { normalizeRedirects } = require("./normalize");
+const { toNetlify, toApache, toHtmlPage, toOutputPath } = require("./formats");
+
+const DEFAULTS = {
+  redirects: {},
+  defaultStatus: 301,
+  netlify: true,
+  apache: false,
+  html: false,
+  netlifyFile: "_redirects",
+  apacheFile: ".htaccess",
+  log: true,
+};
+
+function readExisting(file) {
+  if (!fs.existsSync(file)) return "";
+  const content = fs.readFileSync(file, "utf8");
+  return content.endsWith("\n") ? content : `${content}\n`;
+}
+
+module.exports = function redirectsPlugin(eleventyConfig, userOptions = {}) {
+  const options = { ...DEFAULTS, ...userOptions };
+  const list = normalizeRedirects(options.redirects, options.defaultStatus);
+
+  function log(...args) {
+    if (options.log) console.log("[redirects]", ...args);
+  }
+
+  eleventyConfig.on("eleventy.after", async ({ dir }) => {
+    if (list.length === 0) return;
+
+    const outputDir = dir?.output || "_site";
+    fs.mkdirSync(outputDir, { recursive: true });
+
+    if (options.netlify) {
+      const netlifyPath = path.join(outputDir, options.netlifyFile);
+      // Our rules go first: in Netlify's _redirects format the first matching
+      // rule wins, so our specific redirects must take priority over any
+      // broader rule (e.g. a SPA catch-all) already emitted into this file
+      // by a static passthrough copy.
+      const existing = readExisting(netlifyPath);
+      fs.writeFileSync(netlifyPath, toNetlify(list) + existing);
+    }
+
+    if (options.apache) {
+      const apachePath = path.join(outputDir, options.apacheFile);
+      // Preserve (and prepend ahead of) any existing .htaccess content, e.g.
+      // hand-maintained directives (ErrorDocument, mod_deflate, mod_expires)
+      // brought in via a static passthrough copy — this plugin only owns the
+      // Redirect lines, not the whole file.
+      const existing = readExisting(apachePath);
+      fs.writeFileSync(apachePath, toApache(list) + existing);
+    }
+
+    if (options.html) {
+      for (const { from, to } of list) {
+        const outPath = path.join(outputDir, toOutputPath(from));
+        fs.mkdirSync(path.dirname(outPath), { recursive: true });
+        fs.writeFileSync(outPath, toHtmlPage(to));
+      }
+    }
+
+    log(`wrote ${list.length} redirect(s)`);
+  });
+};
+
+module.exports.normalizeRedirects = normalizeRedirects;
+module.exports.toNetlify = toNetlify;
+module.exports.toApache = toApache;
+module.exports.toHtmlPage = toHtmlPage;
+module.exports.toOutputPath = toOutputPath;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@flyewi/eleventy-plugin-redirects",
+  "version": "0.1.0",
+  "description": "Eleventy plugin that generates Netlify _redirects, Apache .htaccess, and static HTML fallback pages from a single redirects config.",
+  "main": "lib/redirects.js",
+  "type": "commonjs",
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "eleventy",
+    "eleventy-plugin",
+    "11ty",
+    "redirects",
+    "netlify",
+    "htaccess",
+    "seo"
+  ],
+  "author": "flyewi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flyewi/eleventy-plugin-redirects.git"
+  },
+  "homepage": "https://github.com/flyewi/eleventy-plugin-redirects#readme",
+  "bugs": {
+    "url": "https://github.com/flyewi/eleventy-plugin-redirects/issues"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@11ty/eleventy": "^2.0.0 || ^3.0.0"
+  },
+  "devDependencies": {
+    "@11ty/eleventy": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "lib"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}