Theme check rules

Theme check is one implementation with four callers: dtc theme check, the local dev MCP’s validate_theme, the Gateway’s POST /themes/{id}/check (the check_theme tool), and publish. A theme that passes locally passes on the server, because it is the same code. Every publish runs theme check first. Any error stops the publish with 422 CHECK_FAILED and the full result; nothing is deployed.

Result

{
  "ok": false,
  "errors": [
    {
      "path": "theme/custom/sections/ingredient-grid.tsx",
      "line": 4,
      "column": 1,
      "rule": "import-resolves",
      "severity": "error",
      "message": "Cannot resolve \"framer-motion\"",
      "hint": "Custom sections may import react, @/theme, @/lib/* and files under theme/custom/."
    }
  ],
  "warnings": []
}

ok is true when there are no errors; warnings do not affect it. line, column and hint are present when the rule can provide them. Pass only (a list of paths) to check just those files.

Rules

Rule	Severity
`json-parse`	error
`builder2-template`	error
`import-resolves`	error
`no-platform-override`	error
`no-placeholder-link`	error
`no-placeholder-text`	error
`no-empty-image`	error
`no-fake-social-proof`	warning
`tsc`	warning on a development theme, error on publish

json-parse

Template, section group and config/settings_data.json files must be valid JSON.

Bad

{ "version": 2, "sections": {}, "order": [], }

Good

{ "version": 2, "sections": {}, "order": [] }

builder2-template

The document must be a valid Builder2 template: within the limits, every id in order present in sections, and every section allowed where it is placed. Unknown section types are reported too.

Bad — is not a registered type, and is not in sections

{
  "version": 2,
  "sections": { "hero": { "type": "hero" }, "popup": { "type": "newsletter-popup" } },
  "order": ["hero", "popup", "faq"]
}

Good

{
  "version": 2,
  "sections": { "hero": { "type": "hero" }, "faq": { "type": "faq" } },
  "order": ["hero", "faq"]
}

import-resolves

Every relative or @/ import in your TSX files must resolve, either to a file in your theme or to a file the platform’s store template ships. Bare package imports other than react are refused: an agent cannot add npm dependencies.

Bad

import { motion } from "framer-motion";
import { Stars } from "./stars";          // no theme/custom/sections/stars.tsx

Good

import { StoreImage, Button } from "@/theme";
import { Stars } from "../components/stars"; // theme/custom/components/stars.tsx exists

no-platform-override

A theme file must not shadow a platform-owned path. Put your code under theme/custom/ or another merchant-owned path instead.

Bad

theme/builder2/sections/Hero.tsx          (platform-owned)

Good

theme/custom/sections/split-hero.tsx      → section type custom-split-hero

no-placeholder-link

A link with nowhere to go must not be rendered. href="#" and href="" are errors.

Bad

<a href="#">Shop now</a>

Good

{shopHref ? <a href={shopHref}>Shop now</a> : null}

no-placeholder-text

Sample copy reaches real customers the moment a theme is published. Lorem ipsum, “Your Store”, “Coming soon” and “Product name” are errors.

Bad

<h2>Coming soon</h2>
<p>Lorem ipsum dolor sit amet.</p>

Good

{heading ? <h2>{heading}</h2> : null}

no-empty-image

An <img> or <Image> with an empty or missing src renders as a broken image. Render nothing instead.

Bad

<img src="" alt="Product" />
<img alt="Product" />

Good

{image ? <StoreImage src={image} alt={name} /> : null}

Hard-coded star ratings and review counts are a warning. Ratings and review counts must come from real review data, or not be shown.

Bad

<span>★★★★★ 4.9 (2,314 reviews)</span>

Good

{reviewCount > 0 ? <Rating value={rating} count={reviewCount} /> : null}

tsc

TypeScript errors in the TSX files you changed. A warning while you work on a development theme, so you can iterate; an error on publish, so code that does not type-check never goes live.

Bad

export default function Banner({ settings }: SectionRenderProps) {
  const columns: number = settings.columns; // 'unknown' is not assignable to 'number'

Good

export default function Banner({ settings }: SectionRenderProps) {
  const columns = typeof settings.columns === "number" ? settings.columns : 3;

Running it locally

dtc theme check                 # the whole theme
dtc theme check --json          # the CheckResult document, for scripts and agents

See the CLI guide.

Build with your agent

Theme reference

Result

Rules

json-parse

builder2-template

import-resolves

no-platform-override

no-placeholder-link

no-placeholder-text

no-empty-image

tsc

Running it locally

​Result

​Rules

​json-parse

​builder2-template

​import-resolves

​no-platform-override

​no-placeholder-link

​no-placeholder-text

​no-empty-image

​no-fake-social-proof

​tsc

​Running it locally

Result

Rules

json-parse

builder2-template

import-resolves

no-platform-override

no-placeholder-link

no-placeholder-text

no-empty-image

no-fake-social-proof

tsc

Running it locally