npm - astro-head-check - Versions diffs - 1.0.1 - Mend

astro-head-check 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/LICENSE.md ADDED Viewed

@@ -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 ADDED Viewed

@@ -0,0 +1,133 @@
+# astro-head
+**Build-time `<head>` validation for Astro projects.**
+`astro-head-check` is a lightweight Astro integration that validates essential HTML `<head>` metadata at build time.
+It helps catch SEO and indexing issues *before* deployment — without runtime code, tracking, or dashboards.
+---
+## What it does
+At build time, `astro-head` scans generated HTML files and validates common head metadata:
+- `<title>`
+- `<meta name="description">`
+- `<link rel="canonical">`
+- `<meta name="robots">` (optional)
+It supports:
+- Redirect shim detection (meta refresh pages are skipped)
+- Automatic skipping of 404 pages
+- Configurable checks
+- Warning-only or hard-fail build modes
+---
+## Installation
+```bash
+npm install astro-head-check
+```
+---
+## Usage
+Add the integration to your `astro.config.mjs`:
+```js
+import { defineConfig } from "astro/config";
+import astroHead from "astro-head";
+export default defineConfig({
+  integrations: [
+    astroHead({
+      mode: "warn", // or "error"
+      checks: {
+        title: true,
+        metaDescription: true,
+        canonical: true,
+        robots: true,
+      },
+    }),
+  ],
+});
+```
+---
+## Options
+### `mode`
+- `"error"` (default) — fails the build if issues are found
+- `"warn"` — logs issues but allows the build to complete
+### `checks`
+Enable or disable individual validations:
+```ts
+checks: {
+  title?: boolean;
+  metaDescription?: boolean;
+  canonical?: boolean;
+  robots?: boolean;
+}
+```
+If **all checks are disabled**, the plugin does nothing.
+---
+## Output example
+```text
+[astro-head] checks enabled:
+  ✓ title: enabled
+  ✓ metaDescription: enabled
+  ✓ canonical: enabled
+  ✓ robots: enabled
+[astro-head] summary
+[astro-head] HTML files scanned: 100
+[astro-head] title checked: 75
+[astro-head] metaDescription checked: 75
+[astro-head] canonical checked: 75
+[astro-head] robots checked: 75
+[astro-head] pages with issues: 0
+```
+---
+## What it does *not* do
+- ❌ No runtime JavaScript
+- ❌ No Open Graph enforcement
+- ❌ No structured data or rich results validation
+- ❌ No analytics, telemetry, or tracking
+- ❌ No mutation of HTML output
+This tool is **pure validation only**.
+---
+## Compatibility
+- Astro `^4.0.0` and `^5.0.0`
+- Static and hybrid builds
+- Works alongside other Astro integrations (canonical, robots, IndexNow, etc.)
+---
+## License
+MIT © Velohost
+---
+## Author
+**Velohost**
+https://velohost.co.uk/

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,12 @@
+import type { AstroIntegration } from "astro";
+type AstroHeadOptions = {
+    checks?: {
+        title?: boolean;
+        metaDescription?: boolean;
+        canonical?: boolean;
+        robots?: boolean;
+    };
+    mode?: "error" | "warn";
+};
+export default function astroHead(options?: AstroHeadOptions): AstroIntegration;
+export {};

package/dist/index.js ADDED Viewed

@@ -0,0 +1,124 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export default function astroHead(options = {}) {
+    const checks = {
+        title: options.checks?.title ?? true,
+        metaDescription: options.checks?.metaDescription ?? true,
+        canonical: options.checks?.canonical ?? true,
+        robots: options.checks?.robots ?? true,
+    };
+    const mode = options.mode ?? "error";
+    // If everything is disabled, do nothing
+    const anyCheckEnabled = Object.values(checks).some(Boolean);
+    return {
+        name: "astro-head",
+        hooks: {
+            "astro:build:done": async ({ dir }) => {
+                if (!anyCheckEnabled) {
+                    return;
+                }
+                const distDir = new URL(dir).pathname;
+                const htmlFiles = [];
+                const issues = [];
+                const checkCounts = {
+                    title: 0,
+                    metaDescription: 0,
+                    canonical: 0,
+                    robots: 0,
+                };
+                async function walk(folder) {
+                    const entries = await fs.readdir(folder, { withFileTypes: true });
+                    for (const entry of entries) {
+                        const fullPath = path.join(folder, entry.name);
+                        if (entry.isDirectory()) {
+                            await walk(fullPath);
+                        }
+                        else if (entry.isFile() && entry.name.endsWith(".html")) {
+                            htmlFiles.push(fullPath);
+                        }
+                    }
+                }
+                await walk(distDir);
+                for (const file of htmlFiles) {
+                    const relative = file.replace(distDir, "").replace(/\\/g, "/");
+                    // Skip all 404 variants
+                    if (relative === "/404.html" ||
+                        relative === "404.html" ||
+                        relative.endsWith("/404/index.html")) {
+                        continue;
+                    }
+                    const html = await fs.readFile(file, "utf8");
+                    // Skip redirect shim pages
+                    const isRedirect = /http-equiv=["']refresh["']/i.test(html) &&
+                        /content=["']\d+;\s*url=/i.test(html);
+                    if (isRedirect) {
+                        continue;
+                    }
+                    const problems = [];
+                    // ===== TITLE =====
+                    if (checks.title) {
+                        checkCounts.title++;
+                        const titleMatch = html.match(/<title>(.*?)<\/title>/i);
+                        if (!titleMatch || titleMatch[1].trim() === "") {
+                            problems.push("missing or empty <title>");
+                        }
+                    }
+                    // ===== META DESCRIPTION =====
+                    if (checks.metaDescription) {
+                        checkCounts.metaDescription++;
+                        const descMatch = html.match(/<meta\s+name=["']description["']\s+content=["']([^"']*)["'][^>]*>/i);
+                        if (!descMatch || descMatch[1].trim() === "") {
+                            problems.push("missing meta description");
+                        }
+                    }
+                    // ===== CANONICAL =====
+                    if (checks.canonical) {
+                        checkCounts.canonical++;
+                        const canonicalMatch = html.match(/<link\s+[^>]*rel=["']canonical["'][^>]*href=["']([^"']+)["'][^>]*>/i);
+                        if (!canonicalMatch || canonicalMatch[1].trim() === "") {
+                            problems.push("missing canonical link");
+                        }
+                    }
+                    // ===== ROBOTS =====
+                    if (checks.robots) {
+                        checkCounts.robots++;
+                        const robotsMatch = html.match(/<meta\s+name=["']robots["']\s+content=["']([^"']*)["'][^>]*>/i);
+                        if (robotsMatch && robotsMatch[1].trim() === "") {
+                            problems.push("empty robots meta tag");
+                        }
+                    }
+                    if (problems.length > 0) {
+                        issues.push({ file: relative, problems });
+                    }
+                }
+                // ===== CHECK CONFIG SUMMARY =====
+                console.log("\n[astro-head] checks enabled:");
+                for (const [key, enabled] of Object.entries(checks)) {
+                    console.log(`  ${enabled ? "✓" : "–"} ${key}: ${enabled ? "enabled" : "disabled"}`);
+                }
+                // ===== RUN SUMMARY =====
+                console.log(`\n[astro-head] summary`);
+                console.log(`[astro-head] HTML files scanned: ${htmlFiles.length}`);
+                for (const [key, count] of Object.entries(checkCounts)) {
+                    if (checks[key]) {
+                        console.log(`[astro-head] ${key} checked: ${count}`);
+                    }
+                }
+                console.log(`[astro-head] pages with issues: ${issues.length}`);
+                // ===== REPORT ISSUES =====
+                if (issues.length > 0) {
+                    console.error(`\n[astro-head] head validation issues:`);
+                    for (const issue of issues) {
+                        console.error(`\n• ${issue.file}`);
+                        for (const problem of issue.problems) {
+                            console.error(`  - ${problem}`);
+                        }
+                    }
+                    if (mode === "error") {
+                        throw new Error("[astro-head] build failed due to invalid <head> metadata");
+                    }
+                }
+            },
+        },
+    };
+}

package/package.json ADDED Viewed

@@ -0,0 +1,51 @@
+{
+  "name": "astro-head-check",
+  "version": "1.0.1",
+  "description": "Build-time head and meta validation for Astro projects.",
+  "license": "MIT",
+  "type": "module",
+  "author": {
+    "name": "Velohost",
+    "url": "https://velohost.co.uk"
+  },
+  "homepage": "https://github.com/velohost/astro-head",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/velohost/astro-head.git"
+  },
+  "bugs": {
+    "url": "https://github.com/velohost/astro-head/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "astro",
+    "withastro",
+    "astro-integration",
+    "seo",
+    "meta",
+    "head",
+    "validation",
+    "build-time"
+  ],
+  "peerDependencies": {
+    "astro": "^4.0.0 || ^5.0.0"
+  },
+  "devDependencies": {
+    "astro": "^5.16.6",
+    "typescript": "^5.9.3"
+  }
+}