astro-head-check

v1.0.3

Published

6 days ago

Build-time head and meta validation for Astro projects.

0High
0Medium
0Low

hatfieldaaron

astro withastro astro-integration seo meta head validation build-time

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

npm install astro-head-check

Usage

Add the integration to your astro.config.mjs:

import { defineConfig } from "astro/config";
import astroHead from "astro-head-check";

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:

checks: {
  title?: boolean;
  metaDescription?: boolean;
  canonical?: boolean;
  robots?: boolean;
}

If all checks are disabled, the plugin does nothing.

Output example

[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/

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme