Vite Plugin Shopify Assets

1.0.0 verified Mon Apr 27 auth: no javascript

Vite plugin to watch and copy static assets (e.g., fonts, images, static JS/CSS) into a Shopify theme's assets folder during development and build. Version 1.0.0 is the first stable release, compatible with Vite 5 and 6 and Node 18–22. It works alongside vite-plugin-shopify, but can be used standalone. The plugin copies files from a public directory to the theme's assets folder, supports glob patterns, ignore filters, custom destinations, and rename functions for generating Liquid snippets from SVGs. It keeps the assets folder in sync on dev, watch, and build, ensuring that static assets are available in Shopify without manual copying.

Common errors

error ERR_PACKAGE_PATH_NOT_EXPORTED: Package subpath './dist' is not defined by "exports" in package.json ↓

cause Attempting to import from a subpath that does not exist in package exports

fix

Import only from 'vite-plugin-shopify-assets' which exports the plugin function and types.

error ENOENT: no such file or directory, scandir 'public/' ↓

cause The default publicDir 'public' does not exist in the project root

fix

Create a public/ directory or set the 'publicDir' option in the plugin to an existing directory.

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

cause Package not installed, or project is using CommonJS require but the package is ESM-only

fix

Install with npm i -D vite-plugin-shopify-assets and use ES import syntax.

error TypeError: shopifyAssets is not a function ↓

cause Named import used when package only exports default; or default import used incorrectly

fix

Use default import: import shopifyAssets from 'vite-plugin-shopify-assets'.

Warnings

gotcha The plugin requires the publicDir to be set (defaults to 'public'). If you change publicDir, you must update the plugin configuration accordingly — otherwise assets won't be found and nothing will be copied. ↓

fix Set the 'publicDir' option in shopifyAssets() to match your Vite publicDir value.

gotcha When using targets as objects, the 'dest' option is relative to themeRoot (default: ''), not publicDir. Misunderstanding this can cause assets to be copied to unintended directories. ↓

fix Always make dest relative to themeRoot. For example, 'assets/fonts' becomes 'fonts' if themeRoot is the root.

gotcha The rename function receives (file, ext, src) but the documentation is sparse; the 'src' argument is the full relative path from publicDir, which can be confusing for complex rename logic. ↓

fix Test your rename function with sample files and log the arguments to understand the structure.

Install

npm install vite-plugin-shopify-assets

yarn add vite-plugin-shopify-assets

pnpm add vite-plugin-shopify-assets

Imports

default

wrong

const shopifyAssets = require('vite-plugin-shopify-assets');

correct

import shopifyAssets from 'vite-plugin-shopify-assets'

ESM-only; CJS require not supported as package type is module

shopifyAssets

wrong

import shopifyAssets from 'vite-plugin-shopify-assets'

correct

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

default export is the plugin; named export also available

type Options

wrong

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

correct

import type { Options } from 'vite-plugin-shopify-assets'

TypeScript users should import types as type to avoid runtime import

Quickstart

Basic setup to sync public/ folder assets to theme assets/ folder with vite-plugin-shopify and vite-plugin-shopify-assets.

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

export default defineConfig({
  plugins: [
    shopify(),
    shopifyAssets()
  ]
});