Skip to Content
StoreOSv0.31.0
Themes

Architecture

How StoreOS stores a Fluid theme and renders it on a hosted store.

A Fluid store has two pieces. The theme zip is your code. The theme document is the merchant's layout: which widgets appear, and the settings they filled in. StoreOS renders a page from both.


Upload

Uploading a zip creates a new snapshot. StoreOS checks it the same way as storeos theme check. A zip that fails the check is not stored.

A snapshot that passes is kept as one zip on the CDN, named with that snapshot's id. The id never points at a different zip. Uploading again creates another snapshot. Activating a snapshot makes it the store's live theme. The previous zip stays in place until that snapshot is deleted.

The merchant's published layout is stored beside the snapshot. When they have not published layout changes, the storefront uses config/document.json from the zip. See Layout and document.


A page request

The hosted storefront reads the store's live theme.

  • A catalog theme keeps the built-in storefront.
  • A Fluid theme replaces the pages that theme renders. Account, checkout, and other app routes stay with StoreOS.

For a Fluid page, the storefront loads the zip for the live snapshot, the published theme document, and the store data for that URL. It then renders layout/theme.fluid with the widgets for that context.

The zip is downloaded once for each snapshot on a given storefront server. The server unzips it and keeps that copy in memory. The next visitor to the same store on that server does not download or unzip it again. A different store, a newly activated snapshot, or a new server loads its own copy. Stores are not loaded ahead of time.

The HTML is rendered for that request. It is not reused from a shared cache, because a preview cookie can select another theme for one browser.

The theme document and the store data are loaded on that request and passed into the Fluid engine. They are not part of the unzipped theme.

Publishing in the console writes the theme document. The catalog is the store's products, collections, pages, and posts. The storefront API reads both and hands them to the engine with the unzipped theme. The engine returns HTML and does not keep those inputs.

How a URL becomes a context

The hosted storefront asks the Fluid engine before the built-in storefront. The engine returns HTML, or nothing. Nothing means the built-in storefront renders the request.

The hostname picks the store. A host that is not a store never reaches the engine.

The pathname is then matched to a context. The query string is not part of that match. /search is the search context; ?q= is read later as page data. A dynamic segment is the handle: /products/linen-shirt is the product context with handle linen-shirt.

PathContextHandle
/home
/products/:handleproductproduct handle
/collections/:handlecollectioncollection handle, or all
/pages/:slugpagepage slug
/blogblog
/blog/:handleblog-postpost handle
/searchsearch

Any other path, including /cart and /account, is not a context. /assets/t/<snapshot>/<file> is not a page either. The storefront reads that file from the unzipped theme and returns it.

/checkout and /order-confirmation/:id match a path, but StoreOS does not build a Fluid context for them. The built-in storefront renders those pages.

A known path still falls back to the built-in storefront when the document has no widgets for that context, or when the handle does not exist. A missing product, collection, page, or post is not rendered by the theme.

What the engine receives

For a context the theme can render, the storefront loads three things at once and passes them into the engine:

  1. The unzipped theme, from memory or from the snapshot zip.
  2. The theme document: the published layout, or config/document.json when the merchant has not published one.
  3. The page context: store data for this URL, plus SEO for the document head.

The context name selects pages.<context> in the document. Those widgets go in the main region. Header and footer widgets come from the document's chrome and do not change with the URL.

The page context is the set of variables every template can read. Every page gets shop, collections, request, and settings. The URL adds the main object for that context, such as product or article. The fields are listed under Contexts. settings comes from the theme document, not from the catalog.

SEO (the title, meta tags, and structured data) is not a template variable. The engine puts it in content_for_header.

The engine then renders layout/theme.fluid with four regions:

RegionWhat fills it
content_for_headerStylesheets, fonts, and the page's SEO
content_for_topHeader widgets
content_for_layoutWidgets for this context
content_for_bottomFooter widgets

Each widget file is rendered with the same page context, plus widget and props. A collection or collection-list setting stores only an id in the document. While that widget renders, the engine loads the collection and places it on widget.data. That load is separate from the page context. See Collection data.

Collections

These are the MongoDB collections behind that diagram. The zip file itself is not in MongoDB. storefront__FluidThemeSnapshot.zipKey is the CDN path of the zip.

CollectionPurpose
storefront__TenantThemeMapThe store's live theme. kind is FLUID or CATALOG. themeVersion is the FluidThemeSnapshot id. publishedDocument is the layout the merchant published. draftDocument is the customizer draft.
storefront__FluidThemeSnapshotOne uploaded zip, frozen at upload. zipKey is the CDN path. defaultDocument is a copy of config/document.json for the console. When publishedDocument is empty, the engine reads that file from the unzipped zip.
identity__TenantThe shop: name, description, and logo.
inventory__ProductProducts for the page the visitor opened.
inventory__CollectionCollections, including the ones listed on every page.
pagesA content page for /pages/:slug.
blogsBlog posts for /blog and /blog/:handle.

Assets

asset_url builds a URL that includes the snapshot id, such as /assets/t/<snapshot>/theme.css. The storefront serves that file from the unzipped theme. Because a snapshot's files never change, the browser may keep the file for a year.

Link assets only through asset_url. A fixed path would skip the snapshot and can keep serving an old file after a new snapshot is activated.


Preview

The console opens a snapshot with ?fluid_theme=v:<snapshot>. That sets a cookie in that browser and renders that snapshot instead of the live one. ?fluid_theme=off clears it. Other visitors keep seeing the live theme.

On this page