12 min read

Shopify theme import and the Liquid engine

Merchants upload the theme zip Shopify emails them (Online Store → Themes → Import Shopify theme). The rule the owner set: copy the look exactly, run every function on our own features, and say in plain words what changed. One owner module does all of it: packages/core/src/theme-import/ (server entry index.ts, browser-safe half @commerce/core/theme-import → client.ts).

Pipeline

The engine

engine.ts creates one LiquidJS (MIT) instance per theme version: snippets are served from memory (templates option, no file system), ownPropertyOnly, and render limits (LIQUID_LIMITS, applied by renderBounded): renders are synchronous, so while one runs the whole server waits, for every store on it. One render pass may take 2 s of CPU and write 4 M characters; all renders of one page context together (layout, sections, passes, the canvas’s 60-section batch) 6 s; then the rest render as a comment. Parse and memory caps as before. Shopify-only tags:

Filters (filters.ts, values in filter-values.ts): t (locale files, plurals, interpolation, visible “Translation missing”), asset_url (versioned /theme-assets/<theme>/<file>?v=<checksum>), image_url / image_tag (sizes kept from the image, so width/height match), img_url, stylesheet_tag, script_tag, preload_tag, money and friends (INR through @commerce/money, or a Shopify money_format when one is configured), placeholder_svg_tag, json (escapes <), font_face / font_url / font_modify (families loaded from Google Fonts by the layout), colour maths (color_lighten, color_mix, color_contrast…), link and URL helpers, time_tag, date with Shopify’s named formats, payment_type_svg_tag (our own simple marks), file_url (our stored URL when the Shopify importer copied the file, matched by loose name; the old store’s address only when not; read only for themes that call it), video_tag and media_tag for videos (every mp4 rendition as a <source>, the smaller one with media="(max-width: 749px)", the poster, autoplay/loop/muted/controls), external_video_tag. A video setting reaches Liquid as a VideoDrop with sources (1080 and, when copied, 720 high; themes like Zero Drift pick by source.height) and preview_image; the Customize field is an object (url, mobileUrl, poster.url). Unknown filters pass their input through.

Objects on our data

drops.ts, resource-drops.ts and page-context.ts map our records onto Shopify’s shapes: shop, settings (typed by settings_schema.json: fonts, colours, colour schemes, images), section / block, product / variant (prices in paise as Shopify’s subunits; ids are whole numbers from the UUID v7, numeric-id.ts, because themes write "id": {{ variant.id }} into JSON; /theme-actions/cart-add turns them back with resolveThemeVariantId), collection(s), all_products, linklists, blogs, pages, cart, routes (our paths), request, localization (India, INR), template. Resources read as their handle when used as a key (collections[section.settings.collection]). Our built-in pre-order shows up as a selling plan group named “Pre-order”, which is how pre-order apps mark products on Shopify. Menu links carry link.object (the collection, product, page or blog of their path). Metafields and metaobjects read our custom data, see below.

Metafields and metaobjects

The Shopify importer copies metafields into our extra fields (product and collection owners) and metaobjects into content types and entries, storing Shopify’s namespace and key (and metaobject types) through keyFromName (lower snake case). custom-drops.ts maps them back the same way, so product.metafields.custom['size-guide'] finds custom.size_guide.

Only definitions with storefront access, active entries and published targets are read, under the store’s RLS. Loading goes through the request cache: every owner asked for in a pass is one query per owner type (custom-data.ts, loadMetafields), each content type one query, and entry links are followed three levels deep in the same load; files, products, collections, pages, posts and variants they point at are one query per kind.

Synchronous passes

LiquidJS’s async mode creates a promise per value; React’s development server tracks every promise in a Server Component, which made a home page take 20 s. Renders are therefore synchronous: cache.ts answers from memory and notes anything not loaded, the section is rendered again after one batched load, up to five passes (render.ts, renderUntilComplete). Products (all_products[...], product pickers) and collection products asked for in one pass load in one batch (products, collectionsProducts on the data source). A home page is about 1 s in dev and two passes per section.

Cached renders

The storefront keeps every rendered section and the layout parts per store version, and the theme data Liquid reads per store version too: a page whose sections are all cached runs no Liquid at all. A save, a stock change or a theme publish drops them at once (a Postgres trigger and LISTEN). The cart, the clock and the CSP nonce are handled so one render serves everyone it should: see Storefront performance → Caching.

Where it renders

• Storefront. apps/storefront/src/lib/liquid-theme.ts: when the request’s theme (live, or a verified preview) has a theme_import row, renderTemplate takes every LiquidSection from the render cache or renders the missing ones (renderLiquidSections, one transaction) and the LiquidSection renderer places it inside Shopify’s own wrapper (<div id="shopify-section-template--…__hero" class="shopify-section …">, ids shaped like Shopify’s because themes key CSS on them). The store layout draws the theme’s layout/theme.liquid head (stylesheets, CSS variables), the body markup before the header group and after the footer group (icon sprites, cart drawer, scripts), with the request’s CSP nonce on every <script> the theme’s own source writes (see commerce_script_nonce above). Our own pages (product, cart, search, account) render inside the theme’s header and footer. The checkout (/checkout and everything under it) never does: the layout drops the theme’s shell, header and footer there (liquidLayoutForPath, lib/checkout-path.ts), so the theme’s CSS cannot restyle it and its scripts cannot rewrite it before React hydrates (Zero Drift’s reveal.js wraps every main h1–h3 in a span, which threw hydration error #418). Assets: /theme-assets/<theme>/<file> (route -s/[storeId]/theme-assets/[themeId]/[file]), cached for a year when ?v= matches, CORS-open for the canvas, SVG sandboxed.
• Customize. themes.import.editor returns schemas, the schema locale, colour schemes and the theme’s head; use-liquid-theme.ts turns each {% schema %} into Puck fields (liquidSectionFields: text, textarea/richtext, number/range, select/radio, checkbox, image, colour, colour scheme, product/collection/blog/page/menu handles) passed through metadata.liquid; LiquidSection.resolveFields picks the section’s own. Blocks are one array field whose item fields depend on the block type (customize-liquid-blocks.ts). The canvas asks themes.import.render for HTML (batched, liquid-canvas.ts) with everything that can run removed by sanitize-html (canvasSafeHtml, @commerce/blocks/canvas-html: scripts, frames, <meta>/<base>, every on* handler however quoted, script URLs) — the canvas shares the admin’s origin. The iframe gets the theme’s head instead of our theme CSS (preview-frame.tsx).

Behaviour swap

The theme’s JavaScript runs on the storefront for its look (sliders, reveals, marquees). Calls it makes to Shopify go to our features instead (apps/storefront/src/lib/liquid-shim.ts, inline before any theme script). This is not an emulation of Shopify’s API; each call becomes one of ours.

The same table, in code, is swap.ts (SWAP_TABLE), which also detects each row in a section’s Liquid for the report.

Theme scripts wait for React

An imported page is both the theme’s HTML and a React tree (our swapped-in sections, the layout). The theme’s defer, async and module scripts are parked as inert <script type="text/x-theme-deferred"> placeholders when the Liquid output is placed (apps/storefront/src/lib/liquid-defer.ts, for sections and the layout’s head, before-header and after-footer parts) and run by the shim’s window.__commerceBootTheme() once React has hydrated (components/theme/liquid-boot.tsx: after the layout’s effects and the end of parsing), in document order, each external file once. Classic inline scripts (the js class, settings JSON) still run where they are.

Why: a theme script that ran first edited markup React was about to hydrate (Zero Drift’s lens zoom adds a span to .product-gallery__main, a class our own product section shares). React then rebuilt the page on the client, every Liquid section came back through innerHTML, its scripts never ran again and everything the theme had bound was gone (meteors, reveals, rotating words). The shim also replays the common media="print" onload="this.media='all'" stylesheet pattern, since our CSP blocks inline event handlers.

Tests

packages/core/src/theme-import/engine.test.ts (no database) and import.test.ts (database, fake fetch and DNS, MemoryStorageProvider) run on the fixture theme in packages/core/test/theme-import-fixture.ts. No test touches the network or the owner’s theme.

Not yet

• Product, collection and other resource templates from the theme (they use our pages today).
• Editing the theme’s own settings (settings_schema.json) in Customize; adding new sections from the theme in the Add panel.
• A cart drawer that refreshes in place, predictive search results in the theme’s look.