Krate Docs

#Quality Checks

Compiler-enforced accessibility, SEO, and performance gates.

Krate can enforce accessibility, SEO, and performance rules as part of the build. Checks run against the final rendered HTML - exactly what ships - so a rule can never be fooled by a component that only looks right at author time.

Checks are strictly opt-in: without a checks key in krate.config.ts, krate build never fails for quality. krate check runs the built-in rules on demand.

#Enabling checks

// krate.config.ts
export default defineConfig({
  checks: {
    a11y: "error",
    seo: "warning",
    perf: "warning",
    budget: { js: 150 },       // KB per route
    failOn: "error",
  },
});

With this config, krate build fails when an error-severity finding is produced. krate check runs the same rules and always exits non-zero when a finding meets failOn.

#The krate check command

krate check          # build, then evaluate quality gates
krate check ./site   # explicit project directory

The command builds the site and re-reads the emitted dist/ output, so the report reflects the real artifact. It exits 0 when no finding meets the fail-on threshold, and 1 otherwise - ideal for CI.

# CI
krate check && echo "quality gates passed"

#Built-in rules

Rule Category Default Flags
a11y/img-alt a11y error <img> missing an alt attribute
a11y/heading-order a11y warning skipped heading levels, missing/multiple <h1>
a11y/accessible-name a11y warning icon-only links/buttons with no accessible name
a11y/duplicate-id a11y warning repeated id values
a11y/landmark a11y warning no <main>/<nav>/landmark role on the page
a11y/form-label a11y warning form control with no associated label
a11y/tabindex a11y warning positive tabindex (breaks focus order)
a11y/aria-role a11y warning unknown/invalid ARIA role value
a11y/color-contrast a11y warning inline text/background contrast below 4.5:1
a11y/broken-anchor a11y warning in-page #id link with no matching id
seo/title seo error missing <title> or title over 60 characters
seo/description seo warning missing/over-long meta description
seo/canonical seo warning missing <link rel="canonical">
seo/og seo warning missing Open Graph tags (og:title/og:type/og:url)
seo/og-image seo warning missing or relative og:image
seo/lang seo warning <html> missing lang
seo/broken-link seo warning internal link to an unknown route
seo/duplicate-meta seo warning title/description shared across pages
perf/js-budget perf warning route JS over budget.js
perf/hydration-budget perf warning route hydration bundle over budget.hydration
perf/island-budget perf warning island chunks over budget.islandJS
perf/route-budget perf warning HTML + CSS + JS + islands over budget.route
perf/image-dims perf warning <img> missing width/height (layout shift)

alt="" is accepted as intentional decoration; the a11y/img-alt rule only fires when the attribute is absent.

#Severity & overrides

Each category accepts "error", "warning", "off", or a boolean (true = default severity, false = off). Tune individual rules and suppress noise globally:

checks: {
  seo: "warning",
  rules: {
    "a11y/img-alt": "off",       // disable one rule
    "perf/js-budget": "error",   // escalate one rule
  },
  ignore: ["seo/og"],            // suppress a rule everywhere
  failOn: "error",               // or "warning" for stricter CI
}

failOn sets the minimum severity that fails the build/check. Warnings are still reported (and visible in the output) without failing when failOn: "error" (the default). Only "error" and "warning" are valid: any other value (a typo such as "warnings", or "off") is a config error that lists the valid values, so a mistyped CI gate cannot pass silently. Use enabled: false to run no checks. Severity values elsewhere in checks (categories and rules) accept "error", "warning" or "off", and ignore/custom entries must be strings.

Keys the compiler does not read are not silently dropped: an unknown key in checks or checks.budget (failon instead of failOn), or a rule ID in rules or ignore that starts with a11y/, seo/ or perf/ but names no built-in rule (a11y/img-atl), prints a config warning with the nearest valid name. IDs with any other prefix, such as custom/..., are not checked.

#Perf budgets

Budget values are per-route kilobytes. Four independent budgets are available:

Key Rule Counts
js perf/js-budget page hydration + shared runtime
hydration perf/hydration-budget the route's own hydration bundle
islandJS perf/island-budget asynchronous island chunks referenced by the route
route perf/route-budget HTML + linked CSS + JS + island chunks
checks: {
  perf: "warning",
  budget: {
    js: 100,
    hydration: 40,
    islandJS: 120,
    route: 300,
  },
}

js is the total client-JS budget. hydration isolates the route bundle, so a page can stay small even when a shared runtime grows. islandJS catches an expensive compiled package or several islands on one route. route is the end-to-end transfer weight, including the emitted HTML and same-origin stylesheets. Island chunks are counted once per route even when several islands share a chunk.

The browser conformance gate additionally measures island hydration time from navigation start and compares it with KRATE_HYDRATION_BUDGET_MS (default 1500ms; CI uses 2500ms). This is a test/CI threshold, not a build failure: a slow machine does not fail krate build.

#Custom rules

Author rules in TypeScript and point checks.custom at the module. Custom rules run in the embedded QuickJS runtime (@krate/plugin provides the types) - no Node and no subprocess.

// checks/no-lorem.ts
import { defineCheckRule } from "@krate/plugin";

export default defineCheckRule((page) => {
  const findings = [];
  if (/lorem ipsum/i.test(page.html)) {
    findings.push({
      rule: "custom/no-lorem",
      message: "Remove placeholder copy.",
      severity: "warning",
    });
  }
  return findings;
});
// krate.config.ts
checks: {
  custom: ["./checks/no-lorem.ts"],
}

A custom rule receives:

  • page.route - URL route (e.g. /blog/hello)
  • page.source - source path relative to the project root
  • page.html - the final rendered HTML
  • page.jsBytes - the route's client-JS weight
  • page.ast - the parsed program as a kind-tagged AST document (when available)

and returns an array of { rule?, message, severity?, line?, col?, hint? }. A finding only needs message; everything else has sensible defaults.

#Findings format

Findings reuse the compiler's shared diagnostic format, so they match parse and build errors:

/pricing
    x seo/title  page has no <title>
      hint: Export a <Head><title>...</title></Head> or rely on seo.siteName.
    ! perf/js-budget  route ships 212.4KB of JS (budget 150.0KB)

Last updated: 2026-11-17

Contributors: Noinkin