Theme check rules

Theme check is one implementation with three callers: dtc theme check, 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`	warning
`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 copy of a platform-owned file that differs from the platform version. It is a warning, not an error: the API refuses writes to platform paths (PLATFORM_OWNED), and publishing replaces these files with the platform version, so a change in the copy never ships. Older themes often carry such copies from when they were created. 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, and so is copy written to the merchant about what to write — for example “Say what you sell, in one line”, “A sentence for the person who has never heard of you.” or “Describe your returns window here”. Some starting themes ship with it; replace it with your real text, or clear the setting so nothing renders. One exception is a warning: a header or footer store_name saved as a placeholder (“Your store”), or a footer legal line containing “your store”. The storefront replaces those with your store’s real name when it renders, so they never reach customers. Clear the setting to make that explicit.

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