Astro Integration
Astro Canonical
Make canonical URL correctness non-optional. Enforce canonical rules at build time and fail fast when violations occur.
Last Updated: 01 April 2026
Usage Snapshot
419
Downloads in Last 30 Days
v1.1.0
Latest npm Version
Source: npm registry
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.
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 Delivers
- 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.
FAQs
What does the Astro Canonical plugin do?
Astro Canonical validates canonical URLs at build time and fails the build if any page violates canonical rules.
Does Astro Canonical run at runtime?
No. All validation happens during astro build. There is zero runtime logic or client-side code.
Implementation FAQs
Why does Astro Canonical exist?
Canonical URL errors are often invisible until SEO damage is done. Astro Canonical makes canonical correctness non-optional by enforcing it at build time.
Does Astro Canonical add runtime overhead?
No. The plugin runs exclusively during astro build and produces no runtime code.
What validation rules are enforced?
Each HTML page must include a canonical tag, the URL must be absolute, must start with the configured site, and must respect trailing-slash rules if configured.
How does trailing slash enforcement work?
astro-canonical reads your trailingSlash setting from astro.config.mjs and enforces canonical URLs to match it exactly.
What if trailingSlash is not configured?
If trailingSlash is not set, the plugin enforces canonical presence, absolute URLs, and site matching but does not enforce trailing-slash rules.
Are 404 pages validated?
No. 404.html files are ignored automatically.
Project Links
Source code, package distribution, releases, and documentation.
Need Implementation Details?
Read the FAQs for usage patterns, integration caveats, and rollout guidance.