Run `check`

Run the acceptance gate and read what it tells you — its toolchain, its output shape, and its JSON report.

Goal

Answer “will the platform accept this template?” before you submit it. check is the same gate you run locally and the one the registry re-runs on your submission, so a green run here is the real answer, not a rehearsal.

Its exact flags, stages, byte budgets and exit codes are on its reference page. This page is about running it.

Prerequisites

A workspace with at least one template — Install creates one.

Steps

What it needs installed

npm i -D @homepages/template-cli   # provides the `template-kit` command
npm i -D typescript eslint @typescript-eslint/parser esbuild @homepages/eslint-plugin-template

check runs your toolchain, not a copy of its own — see the reference’s constraints for what that means for the versions you pinned, and the ESLint preset for why a linter stays out of the production install of an app that renders a template. What matters while you are setting up: a missing one is reported by name, with the install line to fix it.

Reading a failure

Every failure prints a stable template-kit/<id>, a file:line where one applies, and a one-line fix hint. The id resolves to its own page under rules/ — go there rather than guessing at the message.

Human output prints one line per template (✓ <key>, or ✗ <key> — N problem(s) followed by each finding), then any workspace-level findings — the dependency gates, and anything whose subject is a pair of templates rather than one of them, such as rendered-class-conflict — then check passed if everything passed. One pass shows you every class of problem at once — fix them together; the stages say why.

The JSON report

--json prints one report object instead, keyed per template so a single-template consumer (the registry, ingesting one submission) and an all-templates consumer (your own CI) parse the same shape:

{
  ok: boolean,
  kitVersion: string,
  templates: {
    [templateKey: string]: {
      ok: boolean,
      diagnostics: { ruleId: string, template?: string, section?: string, file?: string, line?: number, message: string, fix?: string }[],
      // Present only when the template has at least one raster import (see below).
      media?: { path: string, masterBytes: number, derivedBytes: number, passthrough: boolean }[],
    },
  },
  // Workspace-scope findings — evaluated once, not per template.
  workspace: { ok: boolean, diagnostics: { ruleId: string, template?: string, section?: string, file?: string, line?: number, message: string, fix?: string }[] },
}

Each Diagnostic carries a ruleId (template-kit/<id>), the template it belongs to, an optional section and file/line, a message, and a fix.

The media report

A template with at least one photograph imported in a component additionally gets a media report — one entry per master image. Unlike --provenance, it is never gated behind a flag: a passed-through image (no image toolchain in this install — see Assets) is something you should see without asking for it.

Human output prints a Template media: block, one line per master: either that it derived a responsive ladder (with the master’s size and the ladder’s total size), or that it passed through unoptimized because this install has no sharp. --json carries the same facts as the media array above — path is workspace-relative, masterBytes/derivedBytes are raw byte counts, and passthrough is true exactly when no ladder was derived. It never fails a run on its own.

Tracing where a value came from

--provenance adds an inspection block per template — one line per slot of every fixture, slot → kind(ref) = value, where kind is how the value was obtained (fact, computed, authored, or a fixture’s own override). It changes nothing about the default output. Two fixtures print no block, because neither has an origin to report: a synthesized nullability fixture, whose empty value no resolver produced, and a fixture for a section that declares no slots. Every other fixture reports every slot. Combine it with --json to get the same data structured.

The render stage uses the same data: a determinism or rendered-output finding on a defineFixtures fixture is followed by a resolved via: block naming how each slot’s value was obtained.

If a threshold is in your way

The thresholds are platform acceptance criteria, and the reference is explicit that nothing raises them. If a template has a legitimate reason to need an exception, ask the platform team; a workaround that quietly disables a gate will simply fail again at submission.

Commands

template-kit check <template>     # one template
template-kit check --all          # every template in the workspace
template-kit check --json         # the report object instead of human output
template-kit check --provenance   # add the per-slot inspection block

Verify

A passing run exits 0 and ends with check passed; under --json the report’s top-level ok is true. A non-zero exit means a finding, or that the run could not proceed at all.

This command is the third step of the author loop, so a green run is also what every other guide means when it ends there.

Rules that can fire

None — this guide changes no file check inspects.