Claude Code Shopify Development

Shopify is a good target for agent-assisted development and a bad one to be naive about. The good part: themes are files, Liquid is readable, and the Admin API covers almost everything you would otherwise click through. The bad part: several of the platform's behaviours fail silently, and silent failure is exactly the class of problem an agent will not report, because from its point of view the operation succeeded.

This hub covers building and running a Shopify store with Claude Code — theme development, Liquid, SEO, performance, accessibility and the deployment discipline that keeps a live storefront from becoming a place you are afraid to touch.

Who this is for

Developers working on Shopify themes and storefronts who want to use Claude Code on a store that takes real orders. It assumes you can read Liquid and use the CLI or the Admin API. It does not assume you are a Shopify specialist — most of what follows is exactly the material a generalist gets wrong on their first store.

The failures that do not announce themselves

These are the ones worth knowing before you start, because each of them looks like success.

Template settings for a section schema the platform has not seen yet

If you push a JSON template referencing settings or block types that the corresponding section's {% schema %} does not yet define, Shopify accepts the upload and silently discards the settings it does not recognise. No error, no warning. Your template is live, your new setting is simply gone, and the page renders with defaults.

The fix is ordering: push the section .liquid first, let the schema register, then push the template that uses it. The same rule applies to raising max_blocks before pushing a section group that exceeds the old limit — the difference there is that you get a FILE_VALIDATION_ERROR rather than silence, which is the friendlier of the two behaviours.

Files uploaded under a name that already exists

Upload a file whose filename is already in use and Shopify does not overwrite it. It appends a UUID and gives you a new URL. Every page pointing at the old URL keeps serving the old asset, and the "update" you just shipped is not live anywhere. Replacing a file in place means deleting it and re-uploading.

Restricted Liquid contexts

Some templates render with only a subset of the usual Liquid objects available. A reference to an object that does not exist in that context does not raise — it renders empty. If you are generating a machine-readable file such as llms.txt from a template, values that must be correct have to be literals or come from a source you have verified is present, and something has to test that those literals still match reality.

The purchased theme underneath

If you have layered your own templates over a bought theme, every route you have not explicitly claimed falls through to the original. That is usually fine and occasionally not: a collection page rendering in the parent theme's design with an h1 of "Home page" and no title tag is a real page in your sitemap that you have never looked at. Enumerate your routes rather than assuming the ones you built are all that exist.

Shopify SEO: what the platform decides for you

Shopify generates sitemap.xml and you cannot hand-edit it. That is a good constraint and a frequent source of bad advice. The correct lever is publication state: unpublishing a resource from the Online Store channel removes it from the storefront and from the sitemap outright, which is cleaner than a noindex on a URL Google still has to fetch in order to discover the directive.

Several other things are worth knowing before you spend an afternoon on them:

• Titles and descriptions live in the global.title_tag and global.description_tag metafields. Setting them through the API is straightforward; forgetting they exist and writing them into the theme is not.
• Tag archives at /blogs/<blog>/tagged/<tag> inherit the blog's own title and description by default, which means every one of them ships an exact duplicate of the index's title tag. They are also thin by construction. A distinct title plus noindex, follow is usually right.
• Paginated pages repeat page one's title and description unless you add the page number, and a page number past the end of the list still returns 200 with an empty result. Both are crawlable duplicates you created by accident.
• Response headers are not yours. Permissions-Policy has no meta equivalent and simply cannot be set from a theme. Referrer-Policy can, via <meta name="referrer">. Knowing which is which saves a pointless afternoon.

Performance on a platform you do not fully control

A bought theme frequently ships jQuery and a stylesheet in the hundreds of kilobytes, and you will not be removing either without breaking pages you did not write. The productive move is not to fight it globally but to isolate: give the templates that matter their own layout, with their own CSS and no inherited JavaScript, and leave the rest of the store alone.

That is a bigger lever than any amount of image tuning, and it is available specifically because Shopify lets a template declare its own layout.

After that, the ordinary work applies. Reserve dimensions on every image so nothing shifts. Serve responsive sizes rather than one large file — a card rendering at 350 CSS pixels does not need an 800-pixel image, and on a listing page that mistake repeats twenty times. Lazy-load below the fold and, just as importantly, do not lazy-load the element that is going to be your LCP.

Accessibility, and the checks that lie to you

Shopify themes tend to fail accessibility in predictable places: unlabelled icon buttons, colour contrast in secondary text, focus states removed for aesthetics, and form fields with placeholder text doing the job of a label.

The trap in automated checking is false positives that are worse than misses, because they train you to ignore the tool. Two examples from building this store. A tap-target check flagged every link inside a paragraph, because it did not implement the inline exception in WCAG 2.2 success criterion 2.5.8 — targets in a sentence of text are exempt, and a checker without that rule reports a wall of failures on any article. An accessible-name check flagged decorative thumbnails that were deliberately marked aria-hidden and paired with a real text link.

Both were fixed in the checker, not worked around in the markup. A check you have to mentally filter is not a check.

What belongs in a Shopify project's CLAUDE.md

A generic project context file is not much use on a Shopify theme, because the things that go wrong here are platform-specific and an agent has no way to know them. The sections that earn their place:

• Which theme is live and which is development, by ID, and the rule that pushes go to development unless explicitly overridden.
• The push ordering rule — sections before the templates that use their settings — stated as a rule, because the failure is silent and therefore not self-correcting.
• The API version you are pinned to. Mutations change shape between versions; shopPolicyUpdate keying on type rather than id, or productUpdate taking ProductUpdateInput rather than ProductInput, are the kind of detail that costs a round trip every time it is guessed.
• Where credentials live and that they are never printed. Read from a path outside the repository, never logged, never in a commit, never in a Liquid template.
• Which routes you own. So it is obvious when a change lands on a template that falls through to the purchased theme.

Rules that are mechanical belong in a hook rather than here. "Never push to the live theme without the override" is enforceable; a paragraph asking nicely is not.

Deploying without holding your breath

The habits that make Shopify theme work safe are unglamorous:

Develop on an unpublished theme. Push there by default and make pushing to the live theme require an explicit override. This is one environment variable and it removes an entire category of accident.

Keep the theme in git. The theme editor is a second author with write access that never explains itself. Pulling before you push and reviewing the diff is how you find out what it changed.

Verify against the live URL after deploying. Not the preview, not a local render — the real page, after caches settle. This is where you find out that the thing you shipped is not the thing that is serving.

Where to go next

The path below starts with building the store and moves into Shopify-specific SEO. The full hub list underneath adds performance, accessibility and security, all of which apply to a storefront the same way they apply to anything else in production.

For a site that is becoming a Shopify store — or a Shopify store moving elsewhere — the work is a migration: the old URLs mapped into Shopify's structure, redirects imported and tested, metadata carried across, DNS recorded before the domain moves. That is the Website Migration & Replatforming System, which has a WordPress-to-Shopify guide and a Shopify replatforming guide.

For the store that is already live, the work moves into the admin: keeping products, collections, SEO, metafields, inventory and redirects correct across a growing catalogue. That is the Shopify Automation & Admin API Toolkit — the Admin GraphQL API driven from Claude Code, with a preview before every write.