Architecture

The Build Pipeline

The central architectural decision is that components/ is the single source of truth. The Shopify-required sections/ and snippets/ directories are generated build artifacts.

How It Works

On every vite dev or vite build, the custom ll-build-start-plugin (vite/buildStart.js) runs:

Saves group JSON — copies any sections/*.json back into components/groups/ (preserves Shopify admin edits to section groups)
Wipes sections/ and snippets/ completely
Walks components/ and copies .liquid and .json files using these naming rules:

Source	Destination
`components/sections/<name>/index.liquid`	`sections/<name>.liquid`
`components/groups/<name>.json`	`sections/<name>_group.json`
`components/blocks/<path>/index.liquid`	`snippets/blocks.<path>.liquid`
`components/parts/<path>/index.liquid`	`snippets/parts.<path>.liquid`
`components/icons/<name>.liquid`	`snippets/icons.<name>.liquid`
Any non-index `.liquid` file	Path segments joined with dots

Example: components/blocks/layout/header/nav/primary.liquid becomes snippets/blocks.layout.header.nav.primary.liquid

Hot Reload

During vite dev, the ll-hot-reload-plugin (vite/hotReload.js) watches for .liquid and .json changes inside components/. When a file changes, it copies just that file to its flattened destination and triggers a full-page reload.

Component Types

Sections

Full-width Shopify sections with schema definitions. Each section lives in components/sections/<name>/index.liquid and compiles to sections/<name>.liquid.

Sections can include:

index.liquid — the Liquid template with {% schema %} block
index.js — optional JavaScript class (loaded via data-component)
style.scss — optional scoped styles

Blocks

Reusable UI pieces that are rendered inside sections via {% render %}. Located in components/blocks/.

Parts

Small primitives like buttons, form fields, images, and price displays. Located in components/parts/.

Icons

SVG icon partials. Each icon is a single .liquid file in components/icons/.

Groups

Section group JSON definitions in components/groups/. These compile to sections/<name>_group.json and define groups like the header and footer that appear across templates.

Layout Structure

layout/theme.liquid defines the page shell:

liquid

<body>
  {% render 'blocks.custom_grid' %}
  <div class="ll-scroller js-scroller">
    <div class="js-scroll-content">
      {% sections 'header_snackbar_group' %}
      {% sections 'header_group' %}
      <main id="app">
        {{ content_for_layout }}
      </main>
      {% sections 'footer_group' %}
    </div>
  </div>
</body>

The main#app element is the boundary between App-level components (persistent chrome like header and overlays) and Page-level components (content that changes on navigation).

Shopify Ignore

The .shopifyignore file excludes source files from Shopify deployment. Only the build outputs (sections/, snippets/, assets/) and standard Shopify directories are deployed — components/, src/, node_modules/, and tooling config stay out.

Architecture ​

The Build Pipeline ​

How It Works ​

Hot Reload ​

Component Types ​

Sections ​

Blocks ​

Parts ​

Icons ​

Groups ​

Layout Structure ​

Shopify Ignore ​