Install and start development

Version 0.1 requires Node.js 22.14 or newer, Vite 8, and Shopify CLI on PATH. The Theme Target must be a Shopify theme directory that contains at least layout/ and snippets/.

Install the plugin in every project that uses it so the Vite config, CLI, and generated Mixer all resolve the same version.

pnpm add -D vite-plugin-shopify-theme

Provide the frontend entry in vite.config.ts:

import { defineConfig } from 'vite'
import shopifyTheme from 'vite-plugin-shopify-theme'

export default defineConfig({
  plugins: [shopifyTheme({ entry: 'src/main.ts' })],
})

Before the first development run, generate and stage the production Mixer and assets. The build also inserts {% render 'vite-mixer' %} before </head> in layout/theme.liquid when the layout does not render the Mixer yet, so stage the layout as well. Then run Theme Run from the Vite project root and pass the real theme directory to --path:

shopify-theme build --path theme-frame
git -C theme-frame add snippets/vite-mixer.liquid layout/theme.liquid assets/
git -C theme-frame commit -m "Initialize Vite assets"
shopify-theme dev --path theme-frame --environment development

theme-frame is an example directory; replace it with the project's Theme Target. --environment is Shopify CLI's own option and is forwarded unchanged. Development only requires the production Mixer in the Git index; the commit follows the repository's first-time workflow, and Mixer Snippet and Git explains why the initial build is required.

With the default devBranches: ["dev"], dev also requires the Theme Target's current Git branch name to start with dev. Change the allowlist or set it to false in configuration if the team uses other branch names.

When development starts, verify that the Shopify preview opens, the browser loads Vite development assets rather than production assets, and an entry-source edit triggers an update. If the branch check, Mixer check, or target lock blocks startup, run doctor and continue with troubleshooting. A warning about existing Shopify dev processes does not block startup.