Shopify Skeleton Theme + Vite

A minimal, carefully structured Shopify theme with a Vite-powered asset pipeline, built for modularity, maintainability, and Shopify best practices.

Features

• Template-specific asset loading (no global JS bloat)

  • Centralized routing in layout/theme.liquid based on request.page_type
  • Global bootstrap in frontend/entrypoints/ts/theme.ts
  • Per-template entrypoints in frontend/entrypoints/ts/*

• Vite + Shopify integration

  • Fast local development with HMR
  • Automatic asset manifest + snippets/vite-tag.liquid generation
  • Remote dev support with tunnel for Shopify domain previews

• TypeScript-ready frontend architecture

  • TS entrypoints in frontend/entrypoints/ts/
  • Shared utilities in frontend/entrypoints/ts/utils/
  • typecheck gate with tsc --noEmit

• Core storefront interactions

  • PDP variant/media/price synchronization + add-to-cart status handling
  • Cart drawer with keyboard accessibility, quantity/remove async flows, and fallback to /cart
  • Cart page async quantity/remove flows with empty/error states
  • Collection sorting, filtering, and progressive load-more behavior
  • Search predictive suggestions with graceful fallback to full search

• Branch-linked deploy workflow

  • Built assets are committed to branch for Shopify Git-connected themes
  • CI validates quality gates (typecheck, vite:build, theme-check)

• AI-ready contributor workflow

  • Generic agent guide in AGENTS.md
  • Architecture + conventions in CLAUDE.md

---

Scripts

• dev: Run Shopify + Vite locally (development environment)
• dev:remote: Run Shopify + Vite with tunnel enabled
• build: Build production assets with Vite
• typecheck: Run TypeScript checks without emitting files
• vite:dev: Start Vite dev server only
• vite:build: Build Vite assets only
• shopify:dev: Start Shopify theme dev server (development environment)

---

Getting Started

1. Install dependencies:

   bun install

2. Create local config files:

   cp .env.example .env
   cp example.shopify.theme.toml shopify.theme.toml

3. Set your store domain in .env:

   SHOPIFY_STORE_DOMAIN=your-store.myshopify.com

4. Start local development:

   bun run dev

5. If you need preview/editor on the Shopify domain:

   bun run dev:remote

---

Project Structure

.
├── assets/                    # Vite-built assets (hashed JS/CSS) + manifest
│   └── .vite/manifest.json
├── blocks/                    # Reusable Liquid blocks
├── config/                    # Theme settings
├── frontend/
│   └── entrypoints/
│       ├── css/
│       │   └── main.css       # Global CSS (loaded on every page)
│       └── ts/
│           ├── theme.ts       # Global bootstrap/shared setup
│           ├── index.ts       # Home
│           ├── product.ts     # PDP
│           ├── collection.ts  # PLP
│           ├── cart.ts
│           ├── search.ts
│           ├── blog.ts
│           ├── article.ts
│           ├── page.ts
│           ├── 404.ts
│           ├── password.ts
│           ├── gift-card.ts
│           └── utils/
├── layout/
│   ├── theme.liquid           # Main layout + centralized JS router
│   └── password.liquid
├── sections/                  # Page sections
├── snippets/
│   └── vite-tag.liquid        # Auto-generated by vite-plugin-shopify
├── templates/                 # JSON templates + gift_card.liquid
├── vite.config.js
├── tsconfig.json
└── package.json

---

Asset Loading Rules

• Always loaded:
  • css/main.css
  • ts/theme.ts
• Template-specific:
  • ts/product.ts, ts/collection.ts, etc.
• Do not render vite-tag in section files.
  • Asset loading is managed in layouts/templates.

---

Customization Contract

• Keep TS modules focused on behavior/state only.

  • Put DOM events, async flows, and state sync in frontend/entrypoints/ts/**.

• Keep Liquid focused on markup/content structure only.

  • Put editable HTML structure in sections/** and snippets/**.

• Treat data-js="..." attributes as a stable public contract between TS and Liquid.

  • You can restyle or rearrange markup as long as required data-js hooks remain intact.

• Search drawer safe customization points:

  • Layout container and spacing in sections/search-drawer.liquid
  • Result card markup inside frontend/entrypoints/ts/search/drawer.ts (createResultItem)
  • Group ordering/labels inside frontend/entrypoints/ts/search/drawer.ts (renderGroups)

• Stable data-js contracts by module:

  • Cart drawer: cart-drawer, cart-open, cart-close, cart-items, cart-empty, cart-subtotal
  • Cart page: cart-page, cart-page-items, cart-page-empty, cart-page-footer, cart-page-subtotal
  • Product: product-form, option-value, thumbnail, add-to-cart, cart-status
  • Collection: collection-root, collection-controls, collection-products, collection-load-more, collection-quick-buy
  • Search drawer: search-drawer, search-open, search-close, search-drawer-input, search-drawer-groups

---

Environment Configuration

• .env (local, gitignored)
  • SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
• shopify.theme.toml (local, gitignored)
  • Shopify CLI environment config (development)
• example.shopify.theme.toml (committed)
  • Template for local environment setup

---

Branch-Linked Shopify Deploy (Important)

If your Shopify theme is connected directly to a Git branch, Shopify does not run Vite build for you.

Required flow:

1. Run:

   bun run build

2. Commit generated files:
   • assets/*
   • assets/.vite/manifest.json
   • snippets/vite-tag.liquid
3. Push the branch

---

Recommended Branch Strategy

• main: production-ready branch (connected to production theme)
• staging: QA/integration branch (connected to staging theme)
• feat/*: feature branches

Flow:

1. Build feature on feat/*
2. PR to staging
3. QA on staging theme
4. Merge staging into main

Enforcement in CI:

• PRs to staging must come from feat/*
• PRs to main must come from staging

Start a Feature Branch

git checkout staging
git pull
git checkout -b feat/<short-feature-name>

Before opening a PR, run local quality gates:

bun run typecheck
bun run build
# Optional when installed locally
theme-check

If the branch is Shopify Git-connected, commit generated build artifacts:

• assets/*
• assets/.vite/manifest.json
• snippets/vite-tag.liquid

---

Alias Examples

Use path aliases from vite.config.js for cleaner imports:

import { addToCart } from '@ts/utils/cart';
import '@css/main.css';

---

Linting Strategy

• TypeScript quality gate: bun run typecheck
• Liquid quality gate: Theme Check in CI (Theme Check job)
• Local checks: bun run typecheck and bun run build (plus optional theme-check)

---

Troubleshooting

• CSS not loading in local preview:
  • Ensure bun run dev is running.
• CSS not loading on myshopify.com preview:
  • Use bun run dev:remote (Chrome loopback/PNA limitation).
• Port conflicts:
  • lsof -nP -iTCP:5173 -sTCP:LISTEN
  • lsof -nP -iTCP:9292 -sTCP:LISTEN

---

License

This project uses the Shopify Skeleton Theme license; see LICENSE.md.