Deployment checklist

Pre-deployment validation checklist for Basker themes. Complete every item before uploading a theme to the CMS. Items are grouped by category and ordered by severity.

Overview

Category	Checks	Blocking
Directory structure	3	Yes -- errors prevent a functional theme
Layouts	2	Yes -- missing default layout breaks rendering
Template schemas	4	Yes -- a missing page template prevents rendering
Block schemas	4	Partial -- schema errors prevent block registration
Assets	3	Partial -- disallowed extensions cause errors
Compatibility	2	No -- warnings only, but strongly recommended
Local testing	3	No -- manual verification steps

Directory structure

Required directories present

Severity: Error Check: The theme contains blocks/, layouts/, and templates/ at the root level.

my-theme/
  blocks/
  layouts/
  templates/

All three directories are required. The upload validator reports an error for each missing directory.

Templates directory is not empty

Severity: Warning Check: The templates/ directory contains at least one .liquid file.

An empty templates/ directory passes validation but produces a warning. The theme will have no renderable pages.

No unsupported root directories

Severity: Warning Check: Root-level directories that are not recognised by Basker (e.g. examples/) are flagged and ignored during processing.

Recognised directories: assets/, blocks/, config/, layouts/, snippets/, templates/.

Layouts

Default layout exists

Severity: Error Check: layouts/default.liquid exists.

This is the fallback layout for all pages. Without it, the upload validator reports an error and pages cannot render.

Default layout contains content placeholders

Severity: Manual Check: layouts/default.liquid includes {{ content_for_header }} in <head> and {{ content_for_layout }} in <body>.

The validator does not check for these placeholders, but pages will be blank or broken without {{ content_for_layout }}.

Template schemas

At least one page template exists

Severity: Error Check: templates/ contains index.liquid, page.liquid, or default.liquid.

templates/
  index.liquid

The theme must include at least one of templates/index.liquid, templates/page.liquid, or templates/default.liquid. Without one of these, the upload validator reports an error and the theme has no default page to render.

All templates have a valid schema tag

Severity: Warning (missing schema), Error (invalid JSON) Check: Every .liquid file in templates/ contains a {% schema %} tag with valid JSON.

{% schema %}
{
  "settings": []
}
{% endschema %}

A missing schema tag produces a warning. Invalid JSON inside the schema tag produces an error.

Template settings is an array

Severity: Warning Check: When present, the settings property in template schemas is a JSON array.

{
  "settings": [
    { "name": "show_title", "label": "Show title", "type": "switch" }
  ]
}

Template block references are valid

Severity: Warning Check: Every block name listed in a template's blocks array corresponds to an existing block schema in blocks/.

{
  "settings": [],
  "blocks": ["text_section", "hero_banner"]
}

If hero_banner has no corresponding block file, the validator reports a warning.

Block schemas

All blocks have a valid schema tag

Severity: Warning (missing schema), Error (invalid JSON) Check: Every .liquid file in blocks/ contains a {% schema %} tag with valid JSON.

Block schema has a name field

Severity: Error Check: The schema JSON includes a name property with a non-empty string value.

{
  "name": "text_section",
  "settings": []
}

Block schema settings is an array

Severity: Error Check: The settings property is a JSON array.

No duplicate block names

Severity: Warning Check: Every block's name value is unique across all blocks in the theme.

The validator reports a warning for each duplicate, identifying both files. Only the first occurrence is registered in the manifest.

Assets

Allowed file extensions only

Severity: Error Check: All files in assets/ use one of the allowed extensions.

Allowed extensions:

Category	Extensions
Stylesheets	`.css`
Scripts	`.js`
Data	`.json`
Images	`.gif`, `.ico`, `.jpg`, `.jpeg`, `.png`, `.svg`, `.webp`
Fonts	`.eot`, `.ttf`, `.woff`, `.woff2`

Files with other extensions produce a validation error.

Image files within size limits

Severity: Warning Check: Image files (.gif, .ico, .jpg, .jpeg, .png, .svg, .webp) do not exceed 1.5 MB (1,500,000 bytes).

Other asset files within size limits

Severity: Warning Check: All asset files (regardless of type) do not exceed 2.5 MB (2,500,000 bytes).

No orphaned assets

Severity: Warning Check: Every file in assets/ is referenced somewhere in the theme's Liquid files via the asset_url filter or a direct assets/ path reference.

Unreferenced assets produce a warning. They are still included in the upload but add unnecessary size.

Compatibility

No deprecated include tags

Severity: Warning Check: Liquid files do not use {% include %}. Use {% render %} instead.

{% render "header" %}

The {% include %} tag is deprecated. The validator flags every file that uses it. {% render %} provides the same functionality with better scoping.

Field types are supported

Severity: Warning Check: All field type values in block and template schemas use supported types.

Supported field types: array, checkbox, code, color, date, dateTime, email, group, hidden, json, number, radio, relationship, richText, select, switch, text, textArea, upload, url.

Common aliases are normalised automatically: richtext to richText, textarea to textArea, datetime to dateTime.

Local testing

Run theme check with warnings

Severity: Manual Check: Execute the theme checker with --fail-level warning and resolve all reported issues.

localstage theme check --theme ./my-theme --fail-level warning

An exit code of 0 confirms no errors or warnings remain.

Preview in LocalStage dev server

Severity: Manual Check: Start the dev server and verify all templates render correctly in the browser.

localstage theme dev --theme ./my-theme

Navigate through all page types in the browser. Confirm layouts, templates, and blocks render without errors.

Verify all templates render

Severity: Manual Check: For each template in templates/, confirm the page loads without a server error. Check the terminal output for Liquid rendering errors.

Pay attention to:

Pages using each template variant
Block rendering within templates (via {% stageblocks %})
Asset loading (stylesheets, scripts, images)
Settings values displaying correctly

Quick-reference checklist

Copy this checklist for use during deployment review.

[ ] blocks/, layouts/, templates/ directories present
[ ] layouts/default.liquid exists
[ ] layouts/default.liquid contains {{ content_for_header }} and {{ content_for_layout }}
[ ] At least one page template (templates/index.liquid, page.liquid, or default.liquid)
[ ] All templates have valid {% schema %} with settings array
[ ] All blocks have valid {% schema %} with name and settings
[ ] No duplicate block names
[ ] Template block references match existing blocks
[ ] Asset files use allowed extensions only
[ ] Image assets under 1.5 MB
[ ] All assets under 2.5 MB
[ ] No orphaned assets
[ ] No {% include %} tags (use {% render %} instead)
[ ] All field types are supported
[ ] localstage theme check --fail-level warning exits with 0
[ ] All templates render correctly in LocalStage dev server

Uploading themes -- How to package and upload a theme to the CMS
Versioning and rollback -- How theme versions are tracked
LocalStage CLI reference -- theme check command details
Validation errors -- Detailed error explanations and fixes
Theme directory structure -- Complete directory and naming reference

On this page