Custom and headless storefronts

Goal

Choose the right way to differentiate your public shop — Brand, Composition, trusted extensions, or a headless app — without adding legacy theme packs inside BlueMatrix.

Who it is for

Tenant admins and store managers who work with agencies, plus developers building a custom storefront. Requires module commerce_platform. Theme/layout changes in the Merchant Dashboard need commerce.themes.manage where applicable.

Preconditions

• Store is reachable in the Merchant Dashboard and (for shoppers) set to Published — live storefront.
• Agencies need a store slug and Commerce API origin (or a same-origin Worker BFF in production).
• Do not add folders under themes/{customer}/ — that path is frozen.

Customization levels (prefer this order)

Level	Who configures it	When to use
1. Brand	Merchant Theme / brand settings	Logo, colors, fonts, custom CSS
2. Composition	Merchant pages / templates / blocks	Standard stores — rearrange homepage and layouts
3. Trusted extensions	Approved publisher + merchant slot assignment	Small add-ons in Composition slots
4. Headless	Agency / engineering	Full-custom UI on Cloudflare Workers (or equivalent)

Steps — standard store (Brand / Composition)

1. Open the Merchant Dashboard → Online store → Theme and Pages.
2. Adjust brand assets and layout with Composition templates — preview, then publish.
3. Keep catalog, shipping, and payments healthy as in Storefront operator tasks.

Steps — trusted extension (agency)

1. Scaffold with npm: npx create-bluemtx-extension my-extension.
2. Host the built entry.js at an immutable URL and register it with BlueMTX (approved publishers only).
3. Assign the extension to a store slot from merchant / ops tools.

Steps — headless storefront (agency)

1. Scaffold: npx create-bluemtx-storefront my-store.
2. Install the client: npm install @bluemtx/storefront-sdk.
3. Set NUXT_PUBLIC_STORE_SLUG and Commerce base URL (empty base URL when the app sits behind a same-origin Worker BFF).
4. Call only public routes /api/v1/stores/{slug}/* — never BlueMatrix ERP or merchant admin APIs from the shopper app.
5. Deploy on Cloudflare Workers + Static Assets (Git builds). Ask BlueMTX to mark the store storefront_runtime=headless and register the production URL.

Public kit (source, docs, releases): github.com/bluemtx/storefront-kit.

Result

Shoppers see your brand or custom app; Commerce remains the source of truth for catalog, cart, checkout, and orders. Connected tenants still sync masters through BlueMatrix.

Hard stops

Symptom	Cause	What to do
Want a “theme pack” folder in the monorepo	Legacy path	Use Brand → Composition → extension → headless instead
SPA CORS errors to Commerce	Cross-origin without allowlist / no BFF	Prefer same-origin Worker BFF; or allowlist origins on Commerce
Checkout / stock wrong in the custom app	App inventing server rules	Keep checkout and inventory decisions on Commerce APIs
Draft store	Not published	Set Published — live storefront under General

Related

• Storefront operator tasks
• Merchant dashboard
• Commerce index
• Develop hub (integrators)