Versioning and rollback

How theme deployments are recorded and how to recover by re-uploading a known-good version

Manage theme changes in Basker CMS. Each upload updates the theme document with a new manifest revision and records validation history. The classic theme flow has no one-click rollback. To roll back, re-upload a known-good theme package. Alternatively, test changes as a separate development theme before you replace the active theme.

Steps

1. Understand version tracking

Each accepted theme upload generates a manifestRevision timestamp in ISO 8601 format (e.g. 2025-06-15T14:30:00.000Z). It marks when Basker generated the current manifest. It is not a restorable version number.

The CMS stores additional data per version:

Data	Description
Manifest revision	ISO timestamp of the latest accepted upload
Theme manifest	Templates, blocks, and settings definitions from the latest upload
Theme logs	Upload results, error and warning counts, uploader, and manifest changes
Theme ZIP	The package currently stored for the theme key

Result: You know what Basker tracks per theme version.

2. Upload a new version to an existing theme

To update a theme without creating a duplicate, provide both the key and themeId fields in the upload request.

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

The key is the theme identifier string (typically the directory name or a UUID assigned on first upload). The themeId is the document ID of the existing theme.

When both are provided, Basker updates the existing theme document rather than creating a new one. Basker replaces the manifest with the new upload and sets the manifestRevision to the current timestamp.

Result: Basker updates the existing theme and records a new upload log entry. The response confirms the update:

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

3. Review validation history

Each upload appends a theme log entry. The list can include:

Field	Description
`createdAt`	ISO timestamp of the upload
`theme`	The theme this entry belongs to
`type`	Whether the entry records an `upload` or a `deploy`
`status`	Overall outcome: `ok`, `warning`, or `error`
`errorCount`	Number of validation errors
`warningCount`	Number of validation warnings
`hasCriticalErrors`	Whether the upload contained critical errors
`triggeredBy`	The user who triggered the upload
`triggeredByLabel`	Display name of that user
`manifestDiff`	What changed between the previous and new version
`validationLogKey`	Reference to the full validation report, stored separately and fetched on demand rather than held inline

To view validation history in the CMS admin:

Navigate to Design > Themes.
Click on the theme.
Open the validation log panel.

Result: A chronological list of upload validation results, showing who uploaded each version and what issues it had.

4. Track deployment changes

When you re-upload a theme that is currently active for a tenant, Basker automatically creates a deployment log entry. This records:

The tenant and theme involved
Who triggered the upload
A manifest diff comparing the previous and new versions (added, removed, and changed templates, blocks, and settings)

Basker creates deployment history only when the re-uploaded theme is the currently selected theme for the site.

Result: Deployment logs provide an audit trail of what changed each time you updated the live theme.

5. Test with development themes

To test a new version without affecting the live site:

Upload the theme as a new theme (omit the themeId field) with a different key, such as my-theme-staging.
Preview it using LocalStage by setting the theme ID to the new document.
Verify templates, blocks, and settings render correctly.
When satisfied, re-upload to the production theme using the original key and themeId.

Alternatively, use LocalStage to preview local changes directly without uploading:

basker theme dev --theme ./my-theme

Result: LocalStage validates changes locally before you deploy them to production.

Check the update

When complete, you will have:

An updated theme with a new manifest revision
Theme logs recording upload results and manifest changes
Deployment logs tracking changes to the active theme
A workflow for testing versions before going live

Verify: In the CMS admin, open the theme and check that the manifestRevision timestamp matches the time of your latest upload. Review the validation log to confirm the new entry appears.

Troubleshooting

"Theme added successfully!" instead of "Theme updated successfully!" You omitted the key or themeId field in the upload request. Basker created a new theme document instead of updating the existing one. Delete the duplicate and re-upload with both fields.

Deployment log not created after re-upload Basker creates deployment logs only when the re-uploaded theme is the currently selected (active) theme for the tenant. If the theme is in the library but not selected, Basker does not generate a deployment log.

Cannot find the theme key The theme key is assigned during the first upload. If you uploaded through the admin without specifying one, Basker generated it. Open the theme details to find the key and document ID before using the update API.

Uploading themes -- How to package and upload a theme
Deployment checklist -- Pre-upload validation checklist
Theme manifest reference -- How the manifest is structured
LocalStage CLI reference -- Local development and validation commands

Versioning and rollback

On this page