Uploading themes

Upload a theme to Basker CMS via the admin UI or the REST API. Uploaded themes are validated, stored, and made available in the theme library.

Prerequisites:

• A Basker CMS account with the custom_themes plan feature enabled
• A valid theme directory containing blocks/, layouts/, and templates/
• Theme validation passing with zero errors (localstage theme check --theme ./my-theme)

Steps

1. Package the theme as a ZIP file

Create a ZIP archive of the theme directory contents. The ZIP must contain blocks/, layouts/, and templates/ at the root level.

cd my-theme && zip -r ../my-theme.zip . && cd ..

Do not ZIP the parent directory itself. The archive root should contain the theme folders directly.

Result: A file called my-theme.zip in the parent directory.

2. Choose an upload method

Option A: Upload via the CMS admin UI

1. Log in to the Basker CMS admin dashboard.
2. Navigate to Design > Themes.
3. Click Upload Theme.
4. Select the ZIP file.
5. Wait for processing to complete.

Result: A validation summary appears showing error and warning counts. The theme is added to the theme library.

Option B: Upload via the REST API

Send a POST request to /api/themes/add-theme with multipart form data.

curl -X POST https://your-cms-domain.com/api/themes/add-theme \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@my-theme.zip" \
  -F "tenant=YOUR_TENANT_ID"

Required fields:

Optional fields:

Result: A 201 response with a validation summary:

{
  "message": "Theme added successfully!",
  "validation": {
    "errors": 0,
    "warnings": 2
  }
}

When updating an existing theme (both key and themeId provided):

{
  "message": "Theme updated successfully!",
  "validation": {
    "errors": 0,
    "warnings": 1
  }
}

3. Activate the theme

After uploading, the theme is available in the theme library but is not yet live. To make it the active theme:

1. Navigate to Design > Themes in the CMS admin.
2. Click on the uploaded theme.
3. Publish the theme if it is in draft state.
4. Set it as the selected theme for your tenant.

Result: The theme is live on your site. A deployment log entry is created if the theme was already the active theme when re-uploaded.

Validation process

When a theme ZIP is uploaded, the CMS processes it through a multi-stage pipeline:

1. ZIP extraction -- The archive is unpacked. macOS metadata (__MACOSX/) is stripped automatically.
2. Schema validation -- Every .liquid file in blocks/ and templates/ is parsed. The {% schema %} JSON is validated for structure, required fields, and field types.
3. Asset integrity -- Asset files in assets/ are checked against the allowed extensions list and size limits (1.5 MB for images, 2.5 MB for other assets).
4. Manifest generation -- A theme manifest is built from the validated schemas. It contains template definitions, block definitions, and settings.
5. Theme storage -- The ZIP is stored in Basker's theme storage.
6. Database write -- The theme document is created or updated with the new manifest and a manifestRevision timestamp.

Validation issues are categorised as errors or warnings and recorded in the validation log. Treat any error-level result as unhealthy: the upload may create or update a theme record, but the theme should not be considered safe to activate until errors are fixed.

Error responses

Result

When complete, you will have:

• A theme document in the CMS with a generated manifest
• The theme ZIP stored in Basker's theme storage
• A validation log entry recording the upload result

Verify: Navigate to Design > Themes in the CMS admin. The uploaded theme should appear in the list with its name and validation status.

Troubleshooting

"Uploading theme zip files requires a plan with custom themes feature" The custom_themes plan feature is not enabled for your account. Contact your administrator to enable it.

"Invalid request" (400) The multipart form data is missing the file field or the tenant field. Ensure both are included in the request.

"This theme is locked to tenant '...' and cannot be uploaded to '...'" The theme's config/settings_schema.json contains a theme_settings entry with a tenant property. This locks the theme to a specific tenant slug. Upload it to the matching tenant or remove the tenant lock from the settings schema.

Theme uploaded but not visible in theme library Check the tenant filter in the admin. The theme is associated with the tenant ID specified during upload. Switch to the correct tenant view.

Related

• Versioning and rollback -- How theme versions are tracked and managed
• Deployment checklist -- Pre-upload validation checklist
• Theme manifest reference -- How the manifest is generated from theme files
• Tutorial -- End-to-end theme creation walkthrough