Deployment

There are three ways code reaches Shopify from this repository, and they are not interchangeable.

Publish a preview for review

Use this for anything a reviewer or a client needs to look at. It never touches the live theme and never reuses a theme from a previous run.

node .claude/skills/deploy-theme-preview/deploy.mjs --store a-sales-affair.myshopify.com

Before it creates anything the helper checks that the working tree is clean, that you are on a named branch, and that the branch exactly matches its pushed upstream. It then runs Theme Check, creates a uniquely named unpublished theme through shopify theme push --unpublished, and prints the commit hash, theme name, theme ID and preview URL.

Commit and push first, including the built assets:

npm run build
git add -- <the files you changed> assets snippets/vite-tag.liquid
git commit -m "Describe the change"
git push

There is no flag for targeting an existing theme, and that is deliberate. This store's themes can be connected to GitHub, and a direct CLI push to a connected theme makes Shopify commit the change back as shopify[bot], producing a loop of incoming and outgoing commits.

Full rules are in .claude/skills/deploy-theme-preview/SKILL.md.

Verify a preview

Open the preview URL and check three things.

The storefront loads without console errors.

The network panel shows no requests to localhost or 127.0.0.1. A request to port 5173 means snippets/vite-tag.liquid was committed while it pointed at the dev server.

The behaviour you changed is present, at both desktop and mobile widths.

Release a new theme version

npm run deploy duplicates the live theme and pushes your code onto the copy. Duplicating rather than pushing to a fresh theme preserves the Theme Store update relationship, which a theme created from scratch loses.

npm run deploy

It runs npm run build first, then:

1. Finds the live theme's ID by listing themes and taking the one whose role is live.
2. Duplicates it, naming the copy from themeNameTemplate and version in package.json. At version 6.7.1 that is Beauty Affairs v6.7.1.
3. Polls every five seconds until Shopify reports the theme is no longer processing, for up to twenty minutes.
4. Pushes the local files to the new theme.

Override the name if you need to:

npm run deploy -- --name "Beauty Affairs v6.8.0 RC1"

If a theme with that name exists you are asked to confirm. --force skips the prompt and appends a timestamp so two themes never share a name.

The new theme is not published. Publishing is a manual step in Shopify Admin, under Online Store, Themes, Actions, Publish.

Bump version in package.json before deploying a new version, or the new theme collides with the previous one's name.

Push an update to an existing theme

npm run push

This builds and pushes to the theme selected by shopify.theme.toml. Use it only for a theme you deployed and that is not connected to GitHub. For anything else, use the preview helper.

Before any deployment

git fetch origin
git merge origin/production
npm run typecheck
npm run lint
npm run build

People skip the merge more than any other step, and skipping it loses work. production carries every theme editor change made since your branch diverged, and a push without it reverts them with no warning. See Branches and theme sync.

Rolling back

Shopify keeps previous themes on the store. The fastest rollback is to publish the previous theme in Shopify Admin, under Online Store, Themes.

That is why npm run deploy creates a new theme rather than overwriting the live one. The previous version stays on the store, intact, ready to republish.

Keep old theme versions on the store. They are the rollback path.

A rollback by republishing reverts code and theme settings together, back to the state that theme was in. Theme editor changes made since it was published are on the newer theme only. Note what a merchandiser has changed recently before rolling back.

What is not automated

There is no deployment pipeline. No workflow builds, tests or publishes this theme. The only GitHub Action in the repository pulls the live theme into production.

Every release is a person running npm run deploy and publishing in Shopify Admin.

Source map