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.
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
npm install astro-head-checkAdd 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,
},
}),
],
});"error"(default) — fails the build if issues are found"warn"— logs issues but allows the build to complete
Enable or disable individual validations:
checks: {
title?: boolean;
metaDescription?: boolean;
canonical?: boolean;
robots?: boolean;
}If all checks are disabled, the plugin does nothing.
[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
- ❌ 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.
- Astro
^4.0.0and^5.0.0 - Static and hybrid builds
- Works alongside other Astro integrations (canonical, robots, IndexNow, etc.)
MIT © Velohost
Velohost
https://velohost.co.uk/