Setup checklist

Fastest path from nothing to a working theme, plus the checks that catch most first-run problems.

New theme

npx @display-studio/vite-plugin-shopify-theme init my-theme --yes
cd my-theme
npm run dev

--yes accepts TypeScript, the detected package manager (npm by default), and Tailwind. Flags: --lang js|ts, --package-manager npm|pnpm|yarn|bun, --no-tailwind, --new, --existing.

Existing theme

cd path/to/theme   # contains assets/, layout/, snippets/
npx @display-studio/vite-plugin-shopify-theme init --existing --yes
npm run dev

If layout/theme.liquid has more than one </head> or </body>, init leaves it untouched and prints the three renders to add by hand.

What init creates

File	Role	Edit it?
vite.config.ts	Declares entries	Yes
frontend/entrypoints/theme.css, theme.ts	Starter entries	Yes
snippets/vite-tag.liquid	Placeholder, then generated by dev/build	No
.vite-shopify-theme.json	Ownership record of generated assets	No
.vite-shopify-theme.lock/	Active-process lock	No
.gitignore, .shopifyignore	Generated and local files excluded	Rarely

Verify it works

1. npm run dev: Vite starts first, then Shopify CLI. The log says Development assets ready at ....
2. Open the preview URL: the <head> contains vite-tag output pointing at Vite.
3. Edit frontend/entrypoints/theme.css: the page updates without a reload.
4. Edit a .liquid file: the page reloads.
5. Stop with Ctrl+C: snippets/vite-tag.liquid returns to its previous content and the lock disappears.
6. npm run build: assets and snippets/vite-tag.liquid are generated for upload.

Common first-run problems

Symptom	Fix
LOCK_ACTIVE	Another Vite process owns this theme. Stop it, or follow Troubleshooting.
THEME_STRUCTURE_INVALID	themeRoot is wrong, or assets/ or the snippet folder is missing.
CONFIG_ENTRIES	A source path in entries does not exist, or an entry name has invalid characters.
Styles missing only in the Theme Editor	See Live Theme Editor with a tunnel.
SNIPPET_SIZE_NEAR_LIMIT warning	The generated snippet approaches Shopify's 256 kB file limit. See Troubleshooting.