vite-plugin-shopify

4.1.2 verified Mon Apr 27 auth: no javascript

Vite plugin that integrates Vite into Shopify theme development. Current stable version is 4.1.2 with support for Vite 5, 6, 7, and 8. It provides automatic entrypoint detection, smart tag generation for scripts and styles, full CDN asset support, and hot reloading via @shopify/theme-hot-reload. Key differentiators: zero-config setup, support for Shopify's strict Liquid parser, and automatic tunnel configuration for development previews. Unlike other Shopify Vite integrations, it handles CORS, modulepreload, and snippet generation out of the box. Release cadence is approximately monthly with minor and patch updates.

Common errors

error Cannot find module 'vite-plugin-shopify' ↓

cause Package not installed or installed as dev dependency but not resolved.

fix

Run 'npm install vite-plugin-shopify --save-dev' (or yarn/pnpm equivalent) and ensure node_modules is present.

error Shopify CLI error: 'render' tag with 'with' syntax is not supported in strict Liquid mode ↓

cause Using deprecated 'with' syntax for vite-tag instead of named parameter syntax.

fix

Change liquid from 'render 'vite-tag' with 'theme.scss'' to 'render 'vite-tag', entry: 'theme.scss''.

error Blocked request: This request has been blocked because the host is not allowed ↓

cause Tunnel domain not in server.allowedHosts when using tunnel: true with Vite 7.

fix

Upgrade to vite-plugin-shopify v4.1.0+ or add the tunnel domain to server.allowedHosts in vite.config.js.

Warnings

breaking v4.0.0 replaces hot reloading with @shopify/theme-hot-reload. You must use @shopify/cli >= 3.77.0. ↓

fix Update @shopify/cli to version >=3.77.0 and follow migration guide for theme-hot-reload.

deprecated Old 'with' syntax for rendering vite-tag (e.g., 'render "vite-tag" with "theme.scss"') is deprecated in favor of named parameter syntax (e.g., 'render "vite-tag", entry: "theme.scss"'). ↓

fix Use the new syntax with named 'entry:' parameter for compatibility with Shopify's strict Liquid parser.

gotcha modulepreload tags are only generated when build.modulePreload is not explicitly set to false. In v4.1.1, a fix ensures they are omitted when set to false. ↓

fix Upgrade to v4.1.1 or later, or set build.modulePreload to false in Vite config to disable modulepreload.

gotcha With tunnel: true, you may get 'Blocked request' errors in Vite 7 due to missing server.allowedHosts config. Fixed in v4.1.0. ↓

fix Upgrade to v4.1.0 or later, or manually configure server.allowedHosts to allow your tunnel domain.

Install

npm install vite-plugin-shopify

yarn add vite-plugin-shopify

pnpm add vite-plugin-shopify

Imports

shopify
wrong
```
const shopify = require('vite-plugin-shopify')
```
correct
```
import shopify from 'vite-plugin-shopify'
```
The plugin is ESM-only and ships TypeScript types. Default import is the recommended way.

default export

wrong

import { shopify } from 'vite-plugin-shopify'

correct

import shopify from 'vite-plugin-shopify'

The package exports a default function. Named import is incorrect.

type imports
wrong
```
import { ShopifyPluginOptions } from 'vite-plugin-shopify'
```
correct
```
import type { ShopifyPluginOptions } from 'vite-plugin-shopify/client'
```
For type definitions of options, import from 'vite-plugin-shopify/client'. The main package only exports the plugin function.

Quickstart

Configure vite-plugin-shopify with default options in a Vite config file. All options are optional.

// vite.config.js
import { defineConfig } from 'vite'
import shopify from 'vite-plugin-shopify'

export default defineConfig({
  plugins: [
    shopify({
      themeRoot: './',
      sourceCodeDir: 'frontend',
      entrypointsDir: 'frontend/entrypoints',
      snippetFile: 'vite-tag.liquid',
      versionNumbers: false,
      tunnel: false,
      themeHotReload: true
    })
  ]
})