Code splitting and theme assets

Code splitting comes from host imports and Vite build configuration; it is not a plugin switch. Split only when the loading boundary or caching benefit is clear. A small theme entry is often easier to verify and ship as one file.

Use dynamic import() for non-critical functionality that loads after an interaction; it produces an asynchronous chunk. Use a Rolldown codeSplitting group under build.rolldownOptions.output for initial dependencies that genuinely benefit from separate caching; it produces an initial chunk.

Output rules

• Entries keep stable names (vite-mixer.js, vite-mixer.css), and the Mixer references them through asset_url, whose version parameter handles cache busting.
• Chunks and asynchronous CSS are content-addressed as vite-mixer.[name].[hash].js|css and loaded relative to the importing module, because Shopify serves assets/ as one flat directory. The build uses a relative base for this reason.
• Initial chunks get <link rel="modulepreload"> tags in the Mixer; dynamically imported chunks load on demand and stay out of the Mixer.

Reserved names and cleanup

Files matching vite-mixer.*.js|css with a middle segment are a reserved namespace. After each build the plugin deletes files in that namespace that the build did not produce, so do not hand-author assets under such names. Commit deleted old chunks together with the new outputs. After splitting, verify stable entry names, preload links, on-demand requests, and the cleanup result. The repository code splitting reference remains the exact reference.