Fehler finden,
bevor sie live gehen
astro-post-audit liest nach jedem astro build das generierte HTML und meldet fehlende Canonicals, kaputte Links, lückenhafte Meta-Tags und Accessibility-Probleme. Statische Analyse, kein Browser, keine externen Dienste.
$ astro build [FAIL] astro-post-audit Errors: 1 Warnings: 1 Info: 0 Files: 12 * blog/post/index.html (2) - Missing canonical tag [canonical/missing] at `head` Remedy: Set `site` in astro.config.mjs and render <link rel="canonical" ... /> in BaseHead. - <img> missing alt attribute [a11y/img-alt] at `img[src='/photo.jpg']` Remedy: Add an `alt` prop to <Image>/<Picture> or the <img> tag.
Ein Audit über das, was wirklich ausgeliefert wird.
Die Integration hängt sich an astro:build:done und prüft die fertigen Dateien in dist/. Der Prüfkern ist in Rust geschrieben; das npm-Paket lädt beim Installieren die passende Binärdatei für macOS, Linux oder Windows. Netzwerkzugriffe gibt es nur, wenn der externe Link-Check eingeschaltet ist.
- 01Nach dem Build — geprüft wird das HTML, das auch auf dem Server landet
- 02Offline — kein Headless-Browser, kein Crawler, kein Account
- 03Steuerbar — Presets, Regel-Overrides und Severity pro Regel-ID
- 04CI-tauglich —
failOn, Baseline und SARIF für GitHub Code Scanning
Drei Schritte bis zum ersten Report.
- 1Installieren
Paket hinzufügen
Als Dev-Dependency. Das
postinstall-Skript lädt die Binärdatei aus den GitHub Releases und prüft ihre SHA-256-Summe.npm i -D @casoon/astro-post-audit - 2Einbinden
Integration eintragen
Wer
@astrojs/sitemapnutzt, setztpostAudit()dahinter. Beide laufen inastro:build:done, in Array-Reihenfolge.integrations: [sitemap(), postAudit()] - 3Bauen
Build starten
Das Audit läuft automatisch mit. Mit
failOn: 'errors'bricht der Build bei Fehlern ab.astro build
Was geprüft wird.
SEO und Canonical
Canonical vorhanden, absolut, same-origin und selbstreferenzierend; Cluster mehrerer Seiten mit gleichem Canonical; noindex; Trailing-Slash-Konsistenz.
Links, Sitemap, robots.txt
Kaputte interne Links und Fragmente, Orphan-Seiten, Sitemap-Einträge ohne Seite, Disallow: /, Crawl-Delay und Widersprüche zwischen robots.txt und noindex.
HTML und Überschriften
lang, Title, Viewport und Meta-Description mit Längengrenzen; genau eine H1, keine Sprünge in der Heading-Hierarchie.
Accessibility-Heuristiken
Alt-Texte und deren Qualität, Namen für Links und Buttons, Formular-Labels, Landmarks, doppelte IDs, gültige ARIA-Rollen, aria-hidden auf fokussierbaren Elementen.
Open Graph und JSON-LD
og:title, og:image als absolute URL, gültige twitter:card-Werte; JSON-LD-Syntax, doppelte Typen und Entity-Konflikte über Seiten hinweg.
hreflang und i18n
Selbstreferenz, x-default, gegenseitige Verweise und existierende Ziele; Abgleich von html[lang], hreflang und Canonical je Locale-Route.
Bilder, Assets, Payload
Fehlende width/height, Lazy Loading, srcset, kaputte Asset-Referenzen, JS- und CSS-Menge pro Route mit Ausreißer-Erkennung.
Datenübertragung an Dritte
Mit gdpr: true: Google Fonts, direkte YouTube- und Maps-Embeds, öffentliche CDNs und externe Bilder, dazu fehlende SRI-Hashes.
Optionale Module
HTML5-Konformität offline, AI Visibility und llms.txt-Links, UX-Heuristiken, Content Style, C2PA-Nachweise und Astro/Tailwind-Quellanalyse.
Vom Preset zum Produktions-Gate.
// astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
import postAudit from '@casoon/astro-post-audit';
export default defineConfig({
site: 'https://example.com',
integrations: [
sitemap(), // before postAudit()
postAudit({
preset: 'production',
failOn: 'errors',
maxWarnings: 0,
hints: { sourceFiles: true },
reports: {
json: 'audit-report.json',
sarif: 'audit.sarif',
},
rules: {
filters: { exclude: ['404.html'] },
external_links: { enabled: true, fail_on_broken: true },
},
}),
],
});# .github/workflows/build.yml
- name: Build
run: npm run build
- name: Upload SARIF
if: always()
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: audit.sarifEinführen, ohne den Build lahmzulegen.
Auf gewachsenen Projekten meldet der erste Lauf oft Hunderte Findings. Diese Werkzeuge machen den Umstieg schrittweise.
- 01
Baseline
writeBaselinefriert die aktuellen Findings in einer Datei ein. Danach meldet das Audit nur noch Neues. Die Datei gehört ins Repository. - 02
Erst warnen, dann blockieren
Mit
failOn: 'never'und JSON-Report die heuristischen Module einschalten, einzelne Regeln perseverityaufinfosetzen, später auffailOn: 'errors'wechseln. - 03
Go-Live-Gate
goLivemeldetnoindexauf Live-Seiten, falsche Origins in Canonical, OG-Tags und Sitemap sowie verbotene Domains wie Staging-Hosts. Diese Fehler lassen sich nicht herabstufen. - 04
Schnelle lokale Builds
Neu in 0.6.0:
mode: 'fast'schaltet die aufwendige HTML5-Validierung ab.SKIP_AUDIT=1überspringt das Audit für einen einzelnen Build.
Zwei Zeilen für bestehende Projekte.
// 1. Run once: freeze the current findings
postAudit({ writeBaseline: true, baseline: '.audit-baseline.json' })
// 2. From then on: only new findings are reported
postAudit({ baseline: '.audit-baseline.json' })Was ein statisches Audit nicht sieht.
astro-post-audit liest Dateien. Alles, was erst im Browser entsteht, bleibt außen vor.
Kein Rendering
Keine Farbkontraste, kein Layout, kein Verhalten von JavaScript zur Laufzeit. Dafür braucht es ein Audit im echten Browser.
Heuristiken sind keine WCAG-Prüfung
Die Accessibility-Regeln finden typische Fehler. Eine Konformitätsbewertung nach WCAG ersetzen sie nicht.
Heuristische Module
i18n, Crawl Budget, Render Blocking, Privacy und Structured-Data-Graph arbeiten mit Annahmen und müssen je Projekt per severity abgestimmt werden.
Download beim Installieren
Das postinstall-Skript braucht Zugriff auf GitHub Releases. In abgeschotteten CI-Umgebungen muss die Binärdatei vorab bereitgestellt werden.
Häufige Fragen.
Bricht astro-post-audit den Build bei Fehlern ab?
Nur wenn das konfiguriert ist. Mit failOn: "errors" bricht der Build bei Fehlern ab, mit "warnings" auch bei Warnungen, mit "never" nie. maxWarnings setzt eine Obergrenze für Warnungen. Ohne diese Optionen gibt das Audit nur einen Report aus.
Welche Presets gibt es?
standard, strict, production (Alias für strict), seo, accessibility, performance, relaxed und editorial. Einzelne Einträge unter rules überschreiben den Preset. relaxed ist als Startpunkt für bestehende Sites mit bekannten Problemen gedacht.
Wie unterscheidet sich das von einem Audit im Browser?
astro-post-audit analysiert das statische HTML in dist/ ohne Browser. Browserbasierte Werkzeuge wie auditmysite prüfen die laufende Website und sehen dadurch Rendering, Kontraste, Ladezeiten und JavaScript-Verhalten. Beide Ansätze ergänzen sich.
Wie schalte ich einzelne Prüfungen ab?
Im rules-Objekt lassen sich Module und Optionen einzeln setzen. Unter rules.severity kann jede Regel-ID auf error, warning, info oder off gestellt werden, zum Beispiel "html/title-too-long": "off". filters.exclude nimmt Seiten per Glob aus.
Wie führe ich das Audit auf einer bestehenden Website ein?
Einmal mit writeBaseline: true und einem baseline-Pfad bauen. Das Audit speichert alle aktuellen Findings in dieser Datei. Bei späteren Builds werden nur neue Findings gemeldet. Einträge aus der Datei zu löschen, aktiviert die Prüfung dafür wieder.
Was kostet astro-post-audit und wie wird es ausgeliefert?
Nichts. Das Paket steht unter MIT-Lizenz, es gibt keine API-Kosten und keinen Account. Ausgeliefert wird es über npm (Stand September 2026: 0.6.0) mit Binärdateien aus den GitHub Releases für macOS, Linux und Windows auf x64 und arm64. Die Rust-Crate auf crates.io steht aktuell bei 0.5.5.
Jeder Build geprüft.
Ein Paket in astro.config.mjs, der Report kommt mit dem nächsten astro build.