Not found · Mindhive Theme Docs

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

They are not the same shape. Four rules decide what becomes what:

SourceOutput

src/liquid/**

dist/**

Same paths, copied through · Except sections, which flatten

src/components/**
src/framework/**
src/javascript/**
src/styles/**

dist/assets/main.js
dist/assets/main.css

Compiled into one bundle · Which is what lets islands share state

src/fonts/**
src/media/**

dist/assets/

Flattened · Shopify’s assets/ has no subfolders

src/api/**

deploy/netlify/

Never uploaded to Shopify · Built separately by api:build

Everything below follows from those four lanes.

The folders

Top level is open; the rest is one click away. Each folder carries where its contents end up.

src/liquidBecomes the Shopify theme, path for paththeme

layouttheme.liquid, password.liquid

templatesPage templates. The one place nesting is kept

sectionsFlattened into dist/sections — filenames must be globally unique

jsReact sections — .liquid and .jsx side by side

non-jsPlain Liquid sections

groupsheader, footer, overlay

snippetsjson--* serializers, theme-strings, css-variables

blocksShopify theme blocks

configsettings_schema.json, settings_data.json

localesTranslations. The source for theme-strings

src/componentsReact, atomic designbundle

atomsButton, CarouselArrow

moleculesProductCard, Drawer, FilterPanel, StoreAvailability

organismsCarousel, CollectionGrid

islandsStandalone islands, mounted outside a section

src/frameworkThe public API — one import for every sectionbundle

src/javascriptShared runtime. Reach it through @/framework, not directlybundle

islands.jsxFinds and mounts every section

theme-editor.jsSelection, block attributes

cart.js · overlay.jsShared stores

use-api.js · api-cache.jsuseAPI and request dedup

*.generated.jsComponent and api registries. Never edited by hand

src/stylesTailwind entry and theme tokensbundle

src/fonts · src/mediaFlattened into dist/assetsassets

src/apiServerless gateway. Copied into deploy/, never into the themenot uploaded

operations*.graphql — the Admin allowlist

services*.js — third-party destinations and credentials

_libShared helpers. The underscore keeps them unroutable

viteThe src → dist plugin, and the registriestooling

scriptsapi:build, codegen, deploy targetstooling

shopify-appThe app that provides the App Proxytooling

deployGenerated by api:build. Gitignoredtooling

Notes are hidden on narrow screens. Every folder is listed; only the noteworthy files are.

The two rules worth remembering

Section filenames are global. Shopify has no concept of a section subfolder, so sections/js/hero/hero.liquid and sections/non-js/hero.liquid both become sections/hero.liquid. The build warns rather than silently overwriting one with the other.

The same applies to fonts/ and media/ — Shopify's assets/ is flat.

One bundle, on purpose. Everything under components/, framework/, javascript/ and styles/ compiles into a single assets/main.js. That is what makes cross-island state work without a library: separate React roots still share one module instance, so a module-level variable is already shared between them.

See State across islands.

Where generated files come from

Three files are written by the build and should never be edited by hand. All three are gitignored.

File	Written by	Holds
`src/javascript/components.generated.js`	the Vite plugin	Every section and island component
`src/javascript/api.generated.js`	the Vite plugin	The `api` registry of operations and services
`src/api/_lib/*.generated.js`	`npm run api:build`	Compiled operations and the service index

The first two are regenerated on every theme build, so they cannot go stale. The third is regenerated by api:build, which is also what writes deploy/.

Adding a section

Two files in one folder, named the same:

src/liquid/sections/js/my-thing/
├── my-thing.liquid    ← markup, JSON payload, schema
└── my-thing.jsx       ← default export, receives the JSON as props

No registry to update — the build generates it. See Adding a section.