Build-Time Quality for Astro
Canonical URLs, headings, meta tags, Open Graph, JSON-LD, assets and accessibility – checked at build time, not after deploy.
GitHubCanonical URLs, headings, meta tags, Open Graph, JSON-LD, assets and accessibility – checked at build time, not after deploy.
npm install -D @casoon/astro-post-auditWhat is post-audit?
An Astro plugin that automatically runs quality checks on the generated HTML files after each build. No external services, no crawling, no runtime overhead.
19 check categories from canonical tags to JSON-LD to render blocking – validated directly at build time. Errors fail the build before they go live.
When do you need this?
post-audit closes concrete gaps in the development workflow – for new sites and for existing ones.
Automatic Astro SEO & A11y Tests in the Build
Teams that deploy multiple times per day no longer need a manual checklist for SEO and accessibility. post-audit automatically checks canonical tags, heading structures, and image alt attributes during every build.
Comply with WCAG Accessibility Standards
Projects with legal accessibility obligations must verifiably check heading hierarchies, image alt tags, and skip links. post-audit makes these checks a native part of the CI/CD pipeline.
Optimize Multiple Astro Websites in Parallel
Agencies and web developers maintaining numerous Astro projects can enforce consistent SEO, performance, and code quality standards with a unified configuration.
Gradually Repair Existing Astro Projects
Use the baseline feature to freeze current findings. Subsequent builds only fail when new issues are introduced – perfect for step-by-step optimization.
Two-Minute Setup
import postAudit from '@casoon/astro-post-audit';
export default defineConfig({
integrations: [
postAudit({
failOn: 'errors',
rules: {
canonical: { self_reference: true },
headings: { no_skip: true },
html_basics: { meta_description_required: true },
opengraph: { require_og_title: true, require_og_image: true },
a11y: { require_skip_link: true },
assets: { check_broken_assets: true },
structured_data: { check_json_ld: true },
sitemap: { require: true },
},
}),
],
});
No separate CI step. No external service. Runs directly after astro build.
What gets checked?
Each category addresses mistakes that would otherwise only surface after deploy.
Canonical & URL Normalization
Self-reference, cluster detection (multiple pages sharing a canonical), same-origin enforcement, and trailing-slash consistency.
Heading Hierarchy
H1 present, only once per page, no level gaps (e.g. H2 → H4). WCAG violations are flagged as build errors.
HTML Basics
Title, meta description, html[lang], viewport. Length limits configurable. Missing required fields fail the build.
Open Graph & Social
og:title, og:description, og:image and twitter:card checked for completeness. Incomplete tags lead to broken social previews.
Accessibility
img alt, link and button names, form labels, aria-hidden on focusable elements, generic link text ("click here"), skip link.
Internal Links & Fragments
Broken internal links, query params in internal URLs, fragment validation (#section against actual IDs in the page), orphan page detection.
Structured Data (JSON-LD)
Validates JSON-LD syntax and semantics, detects duplicate @type entries, checks cross-page consistency of @id and entity URLs.
Assets & Content Quality
Missing image and script references, missing width/height (CLS prevention), duplicate titles, descriptions and H1 text across the site.
Hreflang & i18n
Validate hreflang completeness and reciprocity, require x-default, cross-check locale route / lang attribute / canonical consistency across pages.
Security & Privacy
target="_blank" without rel="noopener", mixed content, inline scripts. Plus: third-party domains, missing SRI hashes, CSP readiness and consent indicators.
Render Blocking & Crawl Budget
Synchronous scripts in head, missing preload/preconnect hints for critical resources. URL variants, noindex conflicts and duplicate clusters that waste crawl budget.
More than just checks
Baseline, presets and reports make post-audit practical for existing sites and CI/CD pipelines.
Presets
Start with `strict` or `relaxed` — for new sites or projects with many existing findings that need a gradual rollout.
Baseline
Freeze existing findings with `writeBaseline`. From that point on, the build only fails on new problems — no big-bang refactor required.
Report Files
Write JSON, Markdown and SARIF simultaneously. SARIF is consumed directly by GitHub Code Scanning as inline PR annotations.
Source Hints
`hints.sourceFiles: true` shows the likely source path next to each dist/ finding — e.g. `src/content/blog/post.mdx`.
Why post-audit?
SEO and accessibility errors cost time, rankings and trust – when they're only discovered after deploy.
Zero Runtime Overhead
All checks run at build time. No additional code reaches the browser.
Fail Fast
Errors are reported at build time, not after deploy. No tool ping, no crawling required.
Astro-Native
Integrates directly into astro.config.mjs. No separate CI step, no external service.
MIT License
Open source, free, no dependency on external APIs or accounts.
The CASOON Ecosystem
post-audit is part of a toolchain of open source plugins – all MIT-licensed, all built for Astro.
@casoon/astro-site-files
Generates robots.txt, sitemap.xml with i18n hreflang, llms.txt and security.txt at build time.
@casoon/nosecrets
Prevents API keys and tokens from ending up in the repository – pre-commit hook and manual scan.
@casoon/astro-speed-measure
Measures build performance at integration, Vite plugin and page level. Trend comparisons and CI summaries.
astro-v6-template
Monorepo starter with all four CASOON plugins pre-configured. Cloudflare Workers, i18n, Playwright.
Complement: Live Audits with auditmysite
post-audit checks at build time – static, fast, without a browser. For full accessibility, performance, SEO and security analysis on your live site, auditmysite is the right companion: a CLI tool that evaluates real browser signals via the Chrome DevTools Protocol.
Frequently Asked Questions
How does post-audit help with Astro SEO optimization?
post-audit analyzes the generated HTML directly at build time. It validates SEO-critical elements such as canonical URLs, missing or duplicate meta tags, Open Graph social preview data, correct hreflang attributes, and syntactically valid JSON-LD schema markup.
What accessibility (A11y) checks does the Astro integration run?
The plugin tests WCAG-relevant criteria including missing alt attributes on images, descriptive link and button text, semantic landmark structures (like the presence of a <main> element), duplicate IDs, and valid ARIA roles.
How does post-audit differ from a traditional SEO crawler like auditmysite?
post-audit runs locally and extremely fast during the Astro build process without spawning a real browser, preventing issues before they are deployed. auditmysite analyzes the live website using a headless Chrome browser to evaluate CSS/JS rendering, load times, and visual stability.
Can I disable specific SEO or accessibility checks in the plugin?
Yes. Within the rules object of the configuration in astro.config.mjs, you can disable entire check categories or adjust the severity of specific rule IDs to "off" or "warning" in the severity object.
How do I handle errors on an existing site with many legacy findings?
Enable writeBaseline: true. post-audit will write all current findings into a baseline file. In future builds, these existing warnings and errors will be ignored, and only newly introduced issues will fail the build.
Is the Astro SEO plugin free?
Yes. @casoon/astro-post-audit is published under the MIT license and is completely open source. There are no licensing fees, API costs, or account requirements.
In the Insights Blog
astro-post-audit: SEO and Accessibility Checks Directly After the Build
How the plugin integrates into Astro projects and which errors it prevents – with concrete examples from practice.