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

• Branch-linked deploy workflow

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

---

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.

---

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

---

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.