Validate and upload

The theme is functionally complete. Before uploading, run the theme checker, then package and upload it.

Step 1: Run a strict check

Press c in the dev-server terminal to run the local checker. For a pass that also exits non-zero on warnings, 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 blocks array on a template references a block name that does not exist. This can happen from a typo, or because someone deleted the block but it is still listed.
• An asset file in assets/ that nothing references. These are not fatal, but removing them 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 do not want in the archive. Do not ZIP the parent folder. The archive root must contain blocks/, layouts/, and 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, then Themes.
2. Click Upload theme.
3. Pick the ZIP file.
4. Wait for the upload to finish. During this step, Basker validates the archive and expands it into storage. It also processes every block and template schema into the theme manifest.

When validation completes, you will see error and warning counts. Critical structural errors reject the upload. Other errors can leave an uploaded theme marked unhealthy. Warnings are advisory, for example a block schema missing singular or plural labels, which then defaults to the block's name.

Fix every error before activation. If validation rejects the theme, correct the named structural problem. Repackage the theme. Try again.

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

Step 4: Set the theme live

The newly uploaded theme sits in your theme library, but it is not yet active on the live site. To activate it, go to Design, then Themes. Find the theme. Choose Publish. The next request to your site renders against the new theme.

You can also keep the theme inactive and create a preview link to share instead. The next page explains how.

Step 5: Configure the theme settings

The first time you upload the theme, the editor sees the settings panel. Basker populates it with the schema you defined in config/settings_schema.json. Open the theme settings. Enter the site name, the social links, and anything else you exposed. Save the settings.

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 it to see the new theme without visiting 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.