Skip to main content

​
Liquid Runtime And Storefront SDK

Liquid hosted themes and custom headless storefronts use different runtime models.

​
Quick Decision

You are buildingUse
Hosted Shoppex themeLiquid templates plus the platform commerce runtime
Custom browser storefront outside Shoppex hosting@shoppexio/storefront
Trusted backend integration@shoppexio/sdk and /dev/v1/*
Simple example: a hosted theme product card should use Liquid markup and platform data attributes. A Next.js storefront you host yourself can import @shoppexio/storefront.

​
Hosted Liquid Runtime

Hosted Liquid themes get platform HTML and scripts from the render context: 
{{ themeHeadHtml | raw }}
{{ bootstrapScript | raw }}
{{ storefrontCommerceScriptHtml | raw }}
Product and cart behavior is wired through markup: 
<form
  data-shoppex-product-form
  x-data="productForm({{ product | json_attr | raw }})"
>
  <button type="submit">Add to cart</button>
</form>
The platform script owns:
  • variant selection
  • stock checks
  • quantity clamping
  • cart payload creation
  • coupons
  • hosted checkout redirect

​
Storefront SDK Runtime

Use the Storefront SDK in browser/headless custom storefronts: 
import shoppex from '@shoppexio/storefront';

shoppex.init('my-shop', {
  apiBaseUrl: 'https://api.shoppex.io',
});

const storefront = await shoppex.getStorefront();
console.log(storefront.data?.shop.name);
Do not bundle @shoppexio/sdk into a browser. That package is for trusted backend Developer API calls.

​
Product Images

Storefront product payloads expose different image fields:
  • cdn_image_url for compact cards, listings, search, and cart rows
  • detail_image_url for product detail heroes and galleries
  • images for full gallery work
Liquid producers may precompute the exact image field into the item context. Templates should render the provided field instead of recomputing image choice.

​
Local Dev Data

Liquid local dev supports fixtures and live shop data: 
shoppex theme dev
shoppex theme dev --shop-slug my-shop --no-msw
Storefront SDK custom apps initialize directly with the shop slug: 
shoppex.init('my-shop');

​
Next Steps

Cart & Checkout

Liquid markup hooks for commerce behavior.

Storefront SDK

Browser SDK for custom storefronts outside hosted themes.