Validate and upload

The theme is functionally complete. Before uploading, you'll run the theme checker to catch anything the dev server's looser local validation missed, then package and upload.

Step 1 — Run a strict check

Press c in the dev-server terminal to run the local checker. For a stricter pass that exits non-zero on warnings — the same level the upload validator applies — run it as a standalone command in a separate terminal:

basker theme check --fail-level warning

A clean run prints something like:

Theme check: 0 errors, 0 warnings, 0 info

If you see errors or warnings, the output names the file and the rule. Common things to fix at this stage:

• A block schema missing singular or plural labels.
• A template's blocks array referencing a block name that doesn't exist (typo in the block name, or a block deleted but still listed).
• An asset file in assets/ that nothing references — these aren't fatal, but cleaning them up keeps the bundle small.

The full list of validation rules is on Theme directory structure.

Step 2 — Package the ZIP

From the parent of your theme directory:

cd my-theme
zip -r ../my-theme.zip . -x ".git/*" "*.DS_Store" "*.zip"
cd ..

The -x flags exclude things you don't want in the archive. Don't ZIP the parent folder — the archive root must contain blocks/, layouts/, templates/ directly, not nested inside another directory.

You should now have my-theme.zip next to the theme folder.

Step 3 — Upload through the admin

In your Basker admin:

1. Go to Design → Themes.
2. Click Upload theme.
3. Pick the ZIP file.
4. Wait for the upload to finish — Basker validates the archive, expands it into storage, and processes every block and template schema into the theme manifest.

When validation completes you'll see a summary with an error count and a warning count. Errors block the upload; warnings don't. If validation rejects the theme, the message tells you which file caused the problem — fix it locally, repackage, and try again.

For other ways to upload (API, scripted CI deployments) see Uploading themes.

Step 4 — Set the theme live

The newly uploaded theme is in your theme library but not yet active on the live site. To activate it, find it in Design → Themes and choose Set as live. The next request to your site renders against it.

You can also keep it inactive while you set up a preview link to share — covered on the next page.

Step 5 — Configure the theme settings

The first time the theme is uploaded, the editor sees the settings panel populated with the schema you defined in config/settings_schema.json. Open the theme settings, fill in the site name, the social links, anything else you exposed, and save.

Those values are now what {{ settings.site.name }} and {% for link in settings.social %} resolve to on the live site.

What's next

Share a preview — generate a preview link a colleague can use to see the new theme without going to the live URL.

Going deeper

• Uploading themes — full upload reference, including the API path.
• Deployment checklist — pre-launch checklist for a real deploy.
• The theme manifest — what Basker generates from your files at upload time.