Astro Integration
Astro Canonical
Make canonical URL correctness non-optional. Enforce canonical rules at build time and fail fast when violations occur.
Usage snapshot
Why this plugin exists
Canonical URLs are easy to get wrong at scale — especially on large Astro sites with many contributors or content sources.
astro-canonical validates every generated HTML page during astro build to ensure canonical URLs are present, absolute, and correct.
If a violation is found, the build fails immediately, preventing silent SEO damage from ever reaching production.
What it delivers
Design principles
- Build-time enforcement only
- Fail fast on SEO violations
- No runtime cost or scripts
- Reads existing Astro configuration
- Deterministic, auditable behaviour
What this plugin does
- Requires a canonical tag on every HTML page
- Enforces absolute canonical URLs
- Ensures canonical URLs match your configured site
- Enforces trailing-slash rules from astro.config.mjs
- Ignores 404 pages automatically
- Fails builds immediately on invalid canonicals
- Works with static and hybrid output
Installation
npm install astro-canonical
The plugin integrates with Astro at build time and validates canonical URLs using your existing astro.config.mjs.
Project links
Source code, releases, documentation, and contribution guidelines.
Want the deep dive?
Read the FAQs for implementation details, design rationale, and integration guidance.
View plugin FAQs