Introduction

A Shopify Online Store 2.0 theme built with React, Tailwind v4 and Vite — that still works in the theme editor.

That last part is the whole point. It isn't headless. Merchants get real sections, real blocks, drag-and-drop and live preview. You get React and a build step.

You edit src/. Vite compiles it to dist/, which is a valid Shopify theme and the only thing that ever gets uploaded.

It is built for experienced developers and for enterprise stores with unusual business models — the ones where a conventional theme runs out of road.

Three ideas

Everything else follows from these.

1. Sections render a mount point plus JSON

1<div data-react-component="slideshow">
2  <script type="application/json">{ "settings": … , "blocks": [ … ] }</script>
3</div>

islands.jsx finds every [data-react-component], looks up the matching component by filename, parses the JSON and mounts it. Adding a section is two files and no wiring — the component registry is generated at build time.

2. Liquid owns the data, React owns the rendering

The snippets/json--*.liquid serializers turn Shopify objects into clean JSON — real CDN image URLs, formatted prices, variant and subscription data. React never guesses at Shopify's shape and never re-implements Liquid's filters.

3. src is organised for you, dist is organised for Shopify

Shopify demands a flat, fixed folder layout. You shouldn't have to live in it. A Vite plugin does the translation.

What this buys you

Islands, not a SPA. Each section mounts its own React root. A page with three React sections runs three roots, and a page with none ships no React at all. The theme editor can add, remove and reorder them because they are still just sections.

A real component model. Atomic design under src/components, a shared runtime under src/javascript, and one public API at @/framework.

An escape hatch for data the storefront cannot reach. src/api is a small serverless gateway for the Admin API and third-party services, reached through an App Proxy so it lives on your own domain with no key in the bundle.

What it does not do

It does not replace Liquid. Liquid still renders the page, still queries collections, still owns the cart form. React takes over inside a mount point and nowhere else — which is exactly why the theme editor keeps working.