Skip to content

Theme and Style Preview

An owner can try a different theme, design brief or custom CSS on the real shop, privately, then publish it. Until it is published, shoppers see the shop exactly as before.

For shop owners

Each of these screens has a Preview button next to its save button:

Screen What Preview tries
Settings → Theme The theme you selected
Settings → Design brief The brief as it is in the form (colours, fonts, shape, colour schemes)
Settings → CSS editor The CSS as it is in the editor

Preview opens your shop in a new tab with the change applied. A yellow bar under the header says what you are previewing, with Publish, Discard and Exit preview. You can browse the whole shop (collections, products, the basket) and it all shows the preview.

Previews add up: preview a theme, then a brief, and the preview shows both. Previewing the same thing again replaces the earlier draft.

Settings → Preview (/admin/shopSettings/preview, also where Publish and Discard in the bar take you) lists what the preview changes and has:

  • Open the preview, and a link to share. Anyone with the link sees the preview without signing in, so you can send it to a colleague. They get only Exit preview in the bar.
  • Publish to your shop: each change goes live exactly as if you had saved it on its own screen (the theme is switched, the brief saved and the storefront re-styled, the CSS saved), and the preview ends.
  • Discard: the preview ends and nothing changes.

A preview lasts seven days after its last change. When it is published, discarded or expires, its link stops working and anyone still looking at it sees the live shop again.

From an AI assistant (MCP)

An assistant connected to the shop can use the same preview through manageBranding:

  • previewTheme, previewDesignBrief and previewCustomCss take the same arguments as setTheme, setDesignBrief and setCustomCss, and are checked the same way, but put the change in the preview instead of the live shop. Each answers with the preview's share link and what the preview now changes, so the assistant can give you the link to look at.
  • getDesignBrief shows the open preview, if there is one: its link, what it changes and when it expires.
  • publishPreview puts everything in the preview live and reports what changed, including any brand colours the brief gave a more readable text shade. discardPreview drops it.

It is one preview per shop, so a preview started in the admin and one started by an assistant are the same preview.

The preview also shows every page's unpublished content blocks (Block Drafts). A preview can hold drafts alone, with no design change: the bar then says it is previewing unpublished content, and a page showing its draft links to that page's editor to publish it.

Not covered yet: differences between themes' page layouts beyond the templates themselves (themes share page types, so a switch changes only the theme).

How it works

The preview. One sitePreviews document per site (SitePreview), holding only drafts: the theme name (templateTheme), the draft brief as JSON (briefDraft) with its compiled stylesheet (briefDraftCss, compiled by DesignBriefCssCompiler as saveBrief would), and the draft custom CSS (customCssDraft; empty means "no stylesheet"). A null field means "as the live shop has it". expiresAt carries a TTL index. SitePreviewService creates, reads and discards it (open starts one with no design drafts). Staged block edits are kept in their own contentDrafts collection and shown through this same preview (Block Drafts).

The link and cookie. PagePreviewTokenService.generateSiteToken signs site1|siteId|previewId|expiry with the site's page-preview-signing-key, the same key and format as page preview links (v1|...); neither kind is accepted as the other. The token expires with the preview. GET /preview/site/{token} (SitePreviewController) checks it and sets the bdgr_preview cookie (HttpOnly, SameSite=Lax, lasting until the preview expires), then redirects to the home page. GET /preview/site/exit removes the cookie.

Applying it. On every storefront request with that cookie, TenantResolutionFilter checks the token against the resolved site and that the preview still exists. When both hold, it installs a copy of the SiteContext (SiteContext.copyForPreview) with the preview's theme and sitePreviewId set, in TenantContext, RequestContextHolder and the request attribute; the cached site is never changed. A cookie that no longer works is removed. /admin and /system always get the live site. As a safety net, SitePreviewSaveGuard refuses to save a preview copy of a site.

Caching.

  • A preview response is Cache-Control: private, no-store with X-Robots-Tag: noindex, nofollow. SitePreviewResponse wraps it and drops any caching header a controller sets later.
  • GlobalCSSThemeExtension links /dynamic/css/preview/{previewId}/theme.css and global.css instead of the live files. They are served no-store, only to a request in that preview, as the draft or else the live file. The live /dynamic/css/… files and their five-day cache are untouched.
  • ExtensionService bypasses its extension model cache and doesn't key blocks for RenderedFragmentCache while previewing, as for edit mode.

The bar. SitePreviewInterceptor puts shopPreviewBanner on the model of every rendered page, read by Nova's fragment/breadcrumb :: pageBreadcrumb (included by every theme's header). It isn't called sitePreview, which is the demo-mode badge's boolean (StorefrontChromeInterceptor). Its words are sitePreview.banner.* messages: a theme being tried is named, with "with unpublished design changes" when a brief or stylesheet is staged too. Publish and Discard show only for someone signed in to the admin.

Publishing. SitePreviewPublisher (ai module, beside DesignBriefService) runs each draft through its normal save path: SiteManagementService.updateSite for the theme, DesignBriefService.saveBrief for the brief, CustomCssService.saveGlobalCss for the CSS. Then it deletes the preview.

Over MCP. SiteDesignTools (ai module) has the manageBranding actions above. They reuse the set* actions' checks: the theme name against ThemeService, the brief merge and ColourSchemes.validate / hex colours, and the stylesheet's size and safety checks with CssClassRenamer (renamed old class names come back as notes). previewDesignBrief merges into the brief the preview already holds (SitePreviewService.briefDraft), else the live one, so several calls build one draft; its answer carries the merged draft and its contrast. Each preview action answers {url, expiresAt, changes: {theme, designBrief, customCssChars}}, url being SitePreviewService.previewUrl. publishPreview goes through SitePreviewPublisher and fails when there is nothing to publish; discardPreview answers {discarded}. getDesignBrief (and every manageBranding answer that shows the brief) carries the open preview as preview.

Site data. sitePreviews is never exported or imported with a site (SiteTransferExcludesSitePreviewsTest), and SiteDataDeletionService deletes it with the site.