Deployment checklist

Pre-deployment validation checklist for Basker themes. Complete every item before uploading a theme to the CMS. The upload is rejected only for missing required directories, a missing default page template, or duplicate schema field names. Other errors and warnings still mark the uploaded theme as unhealthy and should be fixed before release.

Category	Checks
Directory structure	3
Layouts	2
Template schemas	4
Block schemas	5
Assets	4
Compatibility	2
Local testing	3

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. Missing one is a critical upload error.

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 ignored root directories

Severity: Warning Check: Do not put production files in examples/; that directory is deliberately excluded from processing. macOS __MACOSX/ metadata is also discarded.

Layouts

Default layout exists

Severity: Error on upload; warning in the local checker 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: Error on upload for invalid JSON; the local checker reports a missing schema as a warning Check: Every .liquid file in templates/ contains a {% schema %} tag with valid JSON.

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

The upload validator treats a missing template schema as an empty schema. The local checker reports it as a warning. Invalid JSON inside a schema tag produces an upload error and a local-checker error.

Template settings is an array

Severity: Warning on upload; Error in the local checker 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 each duplicate. Rename them before upload so block references are unambiguous.

No duplicate field names

Severity: Critical upload error Check: Each field path within a block or template schema is unique.

Duplicate field names make the schema ambiguous and are one of the errors that reject an upload. Names in separate nested groups may match because their complete paths differ.

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 and metadata	`.json`, `.map`, `.txt`, `.xml`, `.webmanifest`
Images	`.gif`, `.ico`, `.jpg`, `.jpeg`, `.png`, `.svg`, `.webp`
Fonts	`.eot`, `.ttf`, `.woff`, `.woff2`
Other supported source	`.vue`

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.

basker 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.

basker 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
[ ] No duplicate field names within a schema
[ ] 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
[ ] basker 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

Deployment checklist

On this page