Validation
The validator checks a template against how the application treats it. Every rule corresponds to something the loader, renderer, sanitizers or storefront engine actually does; there are no general "best practice" rules.
| Severity | Meaning |
|---|---|
| error | The application will not load or render this correctly. |
| warning | The application changes or ignores something you wrote. |
| info | Worth knowing (unused keys and files, optional features). |
node sdk validate [dir] # human-readable
node sdk validate --json # machine-readable: { ok, summary, diagnostics[] }
Exit code 1 when there are errors. The Studio validates continuously (only changed files are re-checked).
Rules
62 rules, read from lib/validate.js.
| Severity | Code | Message |
|---|---|---|
| error | asset-missing | … does not exist in image/. |
| error | css-relative-url | url(…) resolves against /templates/<name>/…, which the application does not serve. Use an absolute /image/… path. |
| error | directive-error | Template engine: |
| error | directive-unbalanced | Template engine: |
| error | js-syntax | JavaScript syntax error: |
| error | json-invalid | template.json is not valid JSON: |
| error | json-type | template.json must contain a JSON object. |
| error | missing-file | … is missing. |
| error | name-invalid | Install name "…" is not allowed by the application (…). |
| error | unsupported-script | <script> elements are removed by the application. Put JavaScript in script.js. |
| error | unsupported-style | <style> elements are removed by the application. Put CSS in styles.css. |
| warning | action-unknown | data-action="…" is not handled by the storefront engine (handle it in script.js). |
| warning | array-too-long | … … has … items; the application uses the first …. |
| warning | asset-large | … is … MB. Large images slow the storefront down. |
| warning | asset-not-served | … will not be served: the application only serves … files from image/ (no hidden files). |
| warning | css-ambiguous | Both style.css and styles.css exist. The page links /style.css, which serves style.css, so styles.css is ignored by the storefront page. |
| warning | css-behavior | behavior: is removed by the application. |
| warning | css-binding | -moz-binding: is removed by the application. |
| warning | css-expression | expression() is removed by the application. |
| warning | css-external-url | url(…) is replaced with "none" by the application (no external URLs in CSS). |
| warning | css-import-removed | @import is removed by the application. Combine the CSS into this file; for fonts use template.json assets.fonts. |
| warning | css-sanitized | The application changes parts of this stylesheet when serving it (sanitizeCss). |
| warning | css-scroll-behavior | The application's CSS sanitizer removes every "behavior:" declaration, which also breaks "scroll-behavior:" (it is served as a dangling "scroll-"). Set smooth scrolling from script.js instead, e.g. document.documentElement.style.scrollBehavior = "smooth". |
| warning | directive-unknown-data | <!-- … … -->: "…" is not provided by the application (always empty/false). |
| warning | duplicate-id | id="…" is used more than once; the engine only finds the first. |
| warning | feature-incomplete | … is present but … element(s) the engine uses with it are missing: …. All … installed templates that implement … have them. |
| warning | font-not-installed | … …: font "…" is not installed in the application (available: …). It is ignored. |
| warning | form-action-removed | Cross-origin form actions are removed by the application (forms may only post to the store itself). |
| warning | generated-hook | #… is created by the storefront engine; defining it in the template causes duplicates. |
| warning | head-removed | Everything inside <head> is discarded by the application (title, meta, links). The application writes its own head. |
| warning | img-relative | src="…" is relative to the page URL and will not find a template file. Use image/… or /image/…. |
| warning | item-dropped | … …[…] has no "…", so the application drops this item. |
| warning | js-sanitized | The application rewrites this line when serving script.js (… is not allowed), so it will not work as written. |
| warning | json-wrong-type | … labels.… should be a string. |
| warning | no-home-section | There is no #section-home: unknown routes fall back to "home", so the page would show no section. |
| warning | number-range | … … should be ≥ …. |
| warning | route-unknown | …="…" is not a storefront route (…); the engine shows the home page instead. |
| warning | section-missing | …="…" links to a route this template does not implement (no #section-…); the engine shows the home page. |
| warning | style-attr-removed | style attributes containing external url() are removed by the application. |
| warning | token-out-of-scope | {…} only has a value inside a … block; here it stays as literal text. |
| warning | token-unknown | {…} is not a placeholder the application provides, so it appears literally on the page. |
| warning | unsafe-url | …="……" is replaced with "#" by the application. |
| warning | unsupported-attr | srcdoc is removed by the application. |
| warning | unsupported-event-attr | …="…" is removed by the application. Bind events in script.js (or use data-action / data-nav). |
| warning | unsupported-script | <script type=" |
| warning | unsupported-tag | <…> elements are removed by the application. |
| warning | value-ignored | … … "…" does not match …, so the application ignores it. |
| warning | value-sanitized | … … contains markup/script text that the application removes. |
| warning | value-truncated | … … is … characters; the application cuts it to …. |
| info | asset-unreferenced | … is not referenced by index.html, styles.css, script.js or template.json (it is still served at … and listed in {TEMPLATE_IMAGES} when it is directly inside image/). |
| info | document-tag | <…> tags are removed; your markup becomes the content of the page body built by the application. |
| info | file-not-served | … is not used by the application… and is left out of builds. |
| info | file-not-used | … is loaded by the template engine but never rendered or served (only index.html, styles.css/style.css and script.js are used). |
| info | img-no-src | <img> without src. |
| info | img-proxied | External image … is loaded through the application's image proxy (/img-proxy). Prefer files in image/. |
| info | js-no-theme | script.js does not set window.StorefrontTheme (optional: labels, icons, colour and hooks for the storefront engine). |
| info | key-not-read | … …: … |
| info | key-unknown | … … is not read by the application. |
| info | label-unknown | … labels.… is not a word the engine uses (known: …). |
| info | raw-token | {{{…}}} prints the value without HTML escaping (the page is sanitized afterwards). |
| info | store-token | {…} is empty until a store is selected (and when the store has no value). Wrap it in <!-- IF … -->…<!-- ENDIF --> to avoid empty markup. |
| info | version-mismatch | theme.json version (…) and template.json version (…) differ; the application reports theme.json's. |