Workflow

Development Setup

Theme development requires two terminal sessions running simultaneously:

Terminal 1 — Vite

npm run dev

Terminal 2 — Shopify CLI

npm run server

• Vite (npm run dev) handles asset compilation (JS/SCSS), the component-to-snippet build pipeline, and hot reload when files in components/ or src/ change.
• Shopify CLI (npm run server, which runs shopify theme dev --live-reload full-page) serves the theme for local preview, syncing Liquid changes to a development store.

Node Version

The project uses Node.js 24 (specified in .nvmrc). Use nvm use to switch:

nvm use

Available Scripts

Script	Command	Purpose
npm run dev	vite dev	Start Vite dev server with hot reload
npm run build	vite build	Production build
npm run server	shopify theme dev --live-reload full-page	Shopify CLI theme preview
npm run lint	biome check	Check linting
npm run lint:fix	biome check --fix	Fix linting issues
npm run format	biome format	Check formatting
npm run format:fix	biome format --fix	Fix formatting

Making Changes

Liquid Changes

1. Edit the component in components/ (never sections/ or snippets/)
2. The hot reload plugin copies the file to its flattened destination
3. Shopify CLI detects the change and syncs to the dev store
4. Browser refreshes automatically

JavaScript Changes

1. Edit the JS file in components/ or src/js/
2. Vite recompiles the module
3. Browser refreshes (full page reload, not HMR for Liquid-driven pages)

Style Changes

1. Edit style.scss in the component folder, or global styles in src/scss/
2. Vite recompiles the CSS bundle
3. Browser updates via HMR (CSS changes are hot-swapped without page reload)

Building for Production

npm run build

This generates:

• assets/ — compiled and hashed JS/CSS bundles
• sections/ — flattened section Liquid files
• snippets/ — flattened snippet Liquid files

Deploying to Shopify

Use Shopify CLI to push the theme:

shopify theme push

The .shopifyignore file ensures only build outputs and standard Shopify directories are deployed. Source files (components/, src/, tooling config) are excluded.

TIP

Use shopify theme push --unpublished to push to an unpublished theme for testing before making it live.

Linting

The project uses Biome for both linting and formatting. It covers:

• components/**/*.js
• src/**
• vite/**
• tailwind/**/*.js
• Root JS/MJS/CJS files

Always run npm run lint:fix before committing.

Shopify Theme Check

Theme Check is configured via .theme-check.yml for Liquid-specific linting. Some rules (like MatchingTranslations) are disabled for the boilerplate.