astro-build-manifest 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Velohost
+
+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,142 @@
+# astro-build-manifest
+
+Static-first build manifest generation for Astro.
+
+`astro-build-manifest` is a minimal Astro integration that outputs a deterministic
+`build-manifest.json` file at build time, describing exactly what pages and assets
+Astro generated.
+
+It is designed for **static sites first** and never runs at runtime.
+
+---
+
+## Why this plugin exists
+
+After a build, teams often ask:
+
+- What routes were actually generated?
+- Did `/about/` build correctly?
+- What files did Astro emit?
+- Why is a page missing in production?
+
+Astro already knows this information internally, but does not expose it in a simple,
+machine-readable way.
+
+`astro-build-manifest` exposes that data safely and honestly.
+
+---
+
+## What it does (v1)
+
+On `astro build`, the plugin writes a file to your output directory:
+
+```
+/build-manifest.json
+```
+
+Example output:
+
+```json
+{
+  "pages": [
+    "/",
+    "/about/"
+  ],
+  "assets": [
+    "/index.html",
+    "/about/index.html",
+    "/_astro/main.abc123.css"
+  ],
+  "generatedAt": "2026-01-08T19:08:18.024Z"
+}
+```
+
+---
+
+## What is included
+
+### Pages
+- All routes Astro generated during the build
+- Normalised with leading and trailing slashes
+- `/` always represents the homepage
+
+### Assets
+- Files emitted by Astro’s build pipeline
+- HTML entrypoints
+- CSS and JavaScript bundles
+- Only public, web-facing paths
+
+---
+
+## What is intentionally excluded
+
+- Files in `/public`
+- Environment variables
+- Runtime state
+- Absolute filesystem paths
+- Server or adapter information
+
+This keeps the manifest deterministic, portable, and safe to expose publicly.
+
+---
+
+## Installation
+
+```bash
+npm install astro-build-manifest
+```
+
+---
+
+## Usage
+
+Add the integration to your `astro.config.mjs`:
+
+```js
+import { defineConfig } from "astro/config";
+import astroBuildManifest from "astro-build-manifest";
+
+export default defineConfig({
+  integrations: [
+    astroBuildManifest()
+  ]
+});
+```
+
+Then run:
+
+```bash
+astro build
+```
+
+---
+
+## Output guarantees
+
+- Static-only
+- Deterministic JSON
+- Public-safe paths only
+- No runtime execution
+
+---
+
+## Versioning
+
+- **v1.x** — static build manifest only
+- **v2 (planned)** — optional public directory inclusion and diffing
+
+---
+
+## License
+
+MIT
+
+---
+
+## Author
+
+Built and maintained by **Velohost**  
+https://velohost.co.uk/
+
+Project homepage:  
+https://velohost.co.uk/plugins/astro-build-manifest/

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import type { AstroIntegration } from "astro";
+/**
+ * astro-build-manifest
+ *
+ * Static-first build manifest plugin for Astro.
+ *
+ * v1 behaviour:
+ * - Lists generated routes (pages)
+ * - Lists build-emitted assets only (JS/CSS/HTML)
+ * - Does NOT scan /public
+ * - Does NOT expose filesystem paths
+ */
+export default function astroBuildManifest(): AstroIntegration;

package/dist/index.js

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * astro-build-manifest
+ *
+ * Static-first build manifest plugin for Astro.
+ *
+ * v1 behaviour:
+ * - Lists generated routes (pages)
+ * - Lists build-emitted assets only (JS/CSS/HTML)
+ * - Does NOT scan /public
+ * - Does NOT expose filesystem paths
+ */
+export default function astroBuildManifest() {
+    return {
+        name: "astro-build-manifest",
+        hooks: {
+            "astro:build:done"({ dir, pages, assets }) {
+                const outDir = new URL(dir).pathname;
+                if (!fs.existsSync(outDir))
+                    return;
+                const manifestPath = path.join(outDir, "build-manifest.json");
+                /**
+                 * Normalise page paths:
+                 * - "" -> "/"
+                 * - ensure single leading + trailing slash
+                 */
+                const pageList = pages.map(p => {
+                    const raw = p.pathname || "";
+                    const trimmed = raw.replace(/^\/+|\/+$/g, "");
+                    return trimmed === "" ? "/" : `/${trimmed}/`;
+                });
+                /**
+                 * Extract PUBLIC build-emitted assets only.
+                 * (/public files are intentionally excluded)
+                 */
+                const assetList = [];
+                for (const urls of assets.values()) {
+                    for (const url of urls) {
+                        if (url.protocol !== "file:")
+                            continue;
+                        const filePath = url.pathname;
+                        if (!filePath.startsWith(outDir))
+                            continue;
+                        const publicPath = "/" + path.relative(outDir, filePath).replace(/\\/g, "/");
+                        assetList.push(publicPath);
+                    }
+                }
+                const payload = {
+                    pages: Array.from(new Set(pageList)).sort(),
+                    assets: Array.from(new Set(assetList)).sort(),
+                    generatedAt: new Date().toISOString()
+                };
+                fs.writeFileSync(manifestPath, JSON.stringify(payload, null, 2), "utf-8");
+                console.log("[astro-build-manifest] wrote /build-manifest.json");
+            }
+        }
+    };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "astro-build-manifest",
+  "version": "1.0.0",
+  "description": "Static build manifest of generated pages and assets for Astro sites",
+  "homepage": "https://velohost.co.uk/plugins/astro-build-manifest/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/velohost/astro-build-manifest.git"
+  },
+  "bugs": {
+    "url": "https://github.com/velohost/astro-build-manifest/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "withastro",
+    "astro-integration",
+    "build",
+    "manifest",
+    "pages",
+    "assets",
+    "static-site"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "peerDependencies": {
+    "astro": "^4.0.0 || ^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "typescript": "^5.0.0"
+  }
+}