Shopify Vite Plugin

Appearance

Return to top
On this page

Getting Started

Overview

Shopify Vite Plugin is a project that aims to integrate Vite as seamlessly as possible with Shopify themes to optimize your theme development experience by providing sensible built-in configurations that should work for the majority of themes and a snippet to load your assets for development and production.

Preset

The recommended and most straightforward approach to get started with Shopify Vite is to use the preset. It's a single command that will:

  • Create a package.json file
  • Add development dependencies on vite and vite-plugin-shopify
  • Update package.json scripts to use launch Vite and Shopify CLI in parallel
  • Create a vite.config.js file
  • Create a .shopifyignore file
  • Load Vite entries in your layout files theme.liquid/password.liquid

To apply the preset, run the following command:

bash
npx @preset/cli apply barrel/shopify-vite --path preset

Installation & Setup

Installing Node

You must ensure that Node.js (16+) and NPM are installed before running Vite and the Shopify plugin:

bash
node -v
npm -v

You can easily install the latest version of Node and NPM using simple graphical installers from the official Node website.

Installing Vite and the Shopify Vite Plugin

First, create a package.json file with npm init -y in the root of your theme's directory structure.

Next, install Vite and the Shopify plugin via NPM.

bash
npm i -D vite vite-plugin-shopify

Finally, adjust your package.json by adding the following scripts:

  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1", 
    "dev": "vite dev", 
    "build": "vite build" 
  },
  "keywords": [],
  "author": "",

Configure Vite

Create a vite.config.js file in your project root directory and add the Shopify plugin. You are free to customize this file based on your needs; check Vite's plugins and config reference for more info.

js
import shopify from 'vite-plugin-shopify'

export default {
  plugins: [
    shopify()
  ]
}

The Shopify Vite Plugin does not require you to specify the entry points for your theme. By default, it treats JavaScript and CSS files (including preprocessed languages such as TypeScript, JSX, TSX, and Sass) within the frontend/entrypoints folder in the root of your project as entry points for Vite.

/
└── frontend/
    └── entrypoints/
        ├── theme.scss
        └── theme.ts

TIP

Read the Configuration Reference of the Shopify Vite Plugin for a full overview of all supported configuration options.

Loading your Scripts and Styles

The Shopify Vite Plugin generates a vite-tag snippet which includes <script> and <link> tags, and all the liquid logic needed to load your assets.

With your Vite entry points configured, you only need to reference them with the vite-tag snippet that you add to the <head> of your theme's layout:

liquid
{% liquid
  # Relative to entrypointsDir
  render 'vite-tag' with 'theme.scss'
  render 'vite-tag' with 'theme.ts'
%}

During development, the vite-tag snippet will load your assets from the Vite development server and inject the Vite client to enable Hot Module Replacement. In build mode, the snippet will load your compiled and versioned assets, including any imported CSS, and use the asset_url filter to serve your assets from the Shopify content delivery network (CDN).

TIP

The vite-tag snippet strips out the version numbers the asset_url filter generates for your production-ready asset by default in favor of loading the hashed file names that Vite generates out of the box.

To enable the version numbers, use the versionNumbers option of the Plugin.

Loading additionalEntrypoints

liquid
{% liquid
  # Relative to sourceCodeDir
  render 'vite-tag' with '@/foo.ts'
  render 'vite-tag' with '~/foo.ts'

  # Relative to project root
  render 'vite-tag' with '/bar.ts' # leading slash is required
%}
js
import shopify from 'vite-plugin-shopify'

export default {
  plugins: [
    shopify({
      additionalEntrypoints: [
        'frontend/foo.ts', // Relative to sourceCodeDir
        'bar.ts' // Relative to project root
      ]
    })
  ]
}

Running Vite

There are two ways you can run Vite. You may run the development server via the dev command, which is useful while developing locally. The development server will automatically detect changes to your files and instantly reflect them in any open browser windows.

Or, running the build command will version and bundle your application's assets and get them ready for you to deploy to production:

bash
# Run the Vite development server...
npm run dev

# Build and version the assets for production...
npm run build

TIP

We recommend adding scripts to your project's package.json file to launch the Shopify and Vite servers in parallel.

Working with JavaScript

Aliases

For convenience, ~/ and @/ are aliased to your sourceCodeDir folder, which simplifies imports:

js
import App from '@/components/App.vue'
import '@/styles/my_styles.css'

React

If you would like to build your front-end using the React framework, then you will also need to install the @vitejs/plugin-react plugin:

bash
npm i -D @vitejs/plugin-react

You may then include the plugin in your vite.config.js configuration file:

js
import { defineConfig } from 'vite'
import shopify from 'vite-plugin-shopify'
import react from '@vitejs/plugin-react'

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

You will need to ensure that any files containing JSX have a .jsx or .tsx extension.

When using React with @vitejs/plugin-react, the vite-tag snippet will include the react refresh script during dev.

Working with Stylesheets

You can learn more about Vite's CSS support within the Vite documentation. If you are using PostCSS plugins such as Tailwind, you may create a postcss.config.js file in the root of your project and Vite will automatically apply it:

js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {}
  }
}

Preloading Stylesheets

You can pass the preload_stylesheet variable to the vite-tag snippet to enable the preload parameter of the stylesheet_tag filter. Use it sparingly. For example, consider preloading only render-blocking stylesheets. Learn more.

liquid
{% render 'vite-tag' with 'theme.scss', preload_stylesheet: true %}

Advanced Customization

Out of the box, the Shopify Vite Plugin uses sensible conventions to help you add Vite with zero configuration to existing Shopify themes; however, sometimes you may need to customize the Plugin's behavior.

Every configuration option is described in the Configuration Reference.

Released under the MIT License.

Made with ❤️ by Barrel