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,previewDesignBriefandpreviewCustomCsstake the same arguments assetTheme,setDesignBriefandsetCustomCss, 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.getDesignBriefshows the open preview, if there is one: its link, what it changes and when it expires.publishPreviewputs everything in the preview live and reports what changed, including any brand colours the brief gave a more readable text shade.discardPreviewdrops 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-storewithX-Robots-Tag: noindex, nofollow.SitePreviewResponsewraps it and drops any caching header a controller sets later. GlobalCSSThemeExtensionlinks/dynamic/css/preview/{previewId}/theme.cssandglobal.cssinstead of the live files. They are servedno-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.ExtensionServicebypasses its extension model cache and doesn't key blocks forRenderedFragmentCachewhile 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.