Skip to main content

​
Liquid Local Development

Local Liquid development uses the same Liquid behavior as Shoppex-hosted storefronts.
ModeUse
Fixture dataFast layout, spacing, responsive, and markup work
Live shop dataCatalog, stock, settings, product detail, and checkout-sensitive work
Theme previewFinal review before publish
Liquid renders HTML. Alpine and the platform commerce script own browser interaction.

​
Commands

shoppex theme pull --theme 11111111-1111-4111-8111-111111111111 --out ./my-theme
cd ./my-theme
shoppex theme dev
Use live shop data when fixture data is not enough: 
shoppex theme dev --shop-slug my-shop --no-msw

​
Source Sync

shoppex theme pull writes .shoppex/theme.json with the linked theme id and source revision. shoppex theme push uploads the full local source snapshot and validates it. It does not publish automatically. shoppex theme dev also persists idle local edits with safe background pushes. If the remote source changed since your pull, the CLI stops instead of overwriting it. Simple example: 
shoppex theme status
shoppex theme push --preview
shoppex theme publish

​
Clean Local AI Workflow

When an AI assistant is editing locally, keep the workspace linked and observable:
1

Start from a fresh pull

Pull the hosted theme before editing so .shoppex/theme.json has the current source revision.
2

Run the Liquid dev server

Keep shoppex theme dev running while the assistant edits. Use fixtures for layout work and --shop-slug my-shop --no-msw for catalog-sensitive work.
3

Edit source only

Change Liquid, CSS, schema, settings, and declared assets. Do not edit generated output or local metadata.
4

Validate before preview

Run shoppex theme validate --include-typecheck or shoppex theme push --preview --include-typecheck.
5

Preview before publish

Review the preview URL and verify cart/checkout behavior before publishing.
Good local prompt: 
Inspect the pulled Liquid theme, find the hero section, change only the headline,
preserve Builder markers and commerce hooks, then run validate and start preview.
Do not publish.
Bad local prompt: 
Rewrite the storefront and publish it.

​
Fixture Data vs Live Data

Use fixtures for layout work: 
shoppex theme dev
Use live data for catalog, stock, settings, or product-detail work: 
shoppex theme dev --shop-slug my-shop --no-msw
Fixtures are deterministic. Live data catches real catalog issues.

​
Common Local Checks

shoppex theme validate --include-typecheck
shoppex theme preview

​
Files An AI Agent Should Avoid

Do not ask an assistant to edit:
  • .shoppex/theme.json
  • .git/
  • node_modules/
  • generated artifacts
  • private API keys or .env files
If the assistant needs a new section or snippet, it must also update theme-package.json so the file is declared.

​
Revision Mismatch

If another user changed the remote draft after your last pull, push fails with a revision conflict. Safe fix: 
shoppex theme pull --force
Only use force push when you intentionally want to replace the newer remote draft: 
shoppex theme push --force

​
Handoff After Local Work

Before handing work to another person or AI agent, leave this summary: 
## Theme
Theme id:
Source revision before:
Source revision after:

## Changed files
-

## Verification
- shoppex theme validate --include-typecheck:
- shoppex theme preview:
- cart/checkout checked:

## Not published
Yes/No:

## Risks or follow-up
-

​
Next Steps

Hosted Theme Sync

Full pull, dev, push, preview, publish workflow.

Package Format

Required Liquid files and manifest rules.