vite-plugin-shopify-theme

Configuration ownership

Separate host Vite settings, plugin responsibilities, and Shopify CLI options so each fact has one owner, with every plugin option and its default.

Before adding a setting, decide whether it belongs to the host project, the plugin, or Shopify CLI. Mixing all three into environment files or wrapper scripts can make direct Vite builds and Theme Run resolve different states.

The host project owns

The frontend entry and any environment-based entry selection;
Source-directory aliases;
Vite listen addresses, ports, HTTPS, and proxies;
CSS and JavaScript frameworks and other Vite plugins;
Dynamic imports and build-level code splitting.

The plugin does not read project environment files or shopify.theme.toml. If the entry depends on an environment variable, load it in vite.config.ts with Vite's loadEnv and pass the result to entry.

The plugin owns

Theme Target resolution and validation, including the #theme alias that points to the theme root;
Narrowing the file watcher to the Theme Target and the entry's source tree;
Build output into the theme assets/ directory, with production file naming;
Development and production Mixer generation;
Reload behavior, the per-target run lock, the Shopify dev process warning, and production verification;
Protection of the development Mixer in supported Git workflows.

Plugin options

Options are passed to shopifyTheme(). An explicit undefined falls back to the default; false is kept where it is an allowed value.

Option	Default	Purpose
`entry`	required	Entry file inside the Vite root, as a root-relative or absolute path
`themePath`	—	Theme root, relative to the current working directory or absolute; required for direct `vite` runs, supplied privately by Theme Run
`snippet`	`"vite-mixer.liquid"`	File name of the generated Mixer Snippet
`devBranches`	`["dev"]`	Branch-name prefixes allowed for `dev`; any match passes, `false` disables the check
`worktree`	`"skip"`	`"skip"` manages the tracked Mixer with `skip-worktree`; `"off"` performs no Git operations
`reload`	`[]`	Extra root-relative directories that trigger a full page reload; `false` disables the plugin's reload, for example when relying on Shopify CLI live reload
`devOrigin`	`"local"`	Vite origin written to the development Mixer: `"local"`, `"network"`, or a complete HTTP(S) origin
`maxDevProcesses`	`0`	Warns when existing Shopify dev processes exceed this number; `false` disables the check
`debug`	`false`	Enables debug logging; read only from this option

Shopify CLI owns

Store identity, authentication, remote themes, Shopify environments, and native command options remain Shopify CLI responsibilities. Theme Run parses its command and local theme path, then forwards applicable Shopify options.

The repository options table is the reference for the installed version. After a configuration change, verify both development and a production build; a running dev server is not sufficient delivery evidence.

Install and start development

Install the plugin in the host project, declare a frontend entry, and start Vite with Shopify theme development through Theme Run.

Theme Run CLI workflows

Choose a command for development, builds, pushes, packages, diagnostics, or restoration, and understand its delivery boundary.