Improve your theme extension development experience with the Shopify Vite Plugin

This article explains how to improve your theme extension development experience by implementing the Barrel-provided Shopify Vite Plugin.

Target audience

People who have experience developing theme extensions

Introduction

Shopify theme extensions (Theme app extensions) are a feature for adding functionality to the storefront when developing Shopify apps.

You can develop them using Liquid, JavaScript, CSS, and more, but compared with regular app development, the local development experience is not very good.

So this time, we will introduce the Shopify Vite Plugin to improve the development experience.

What is the Shopify Vite Plugin?

It is a Vite plugin provided by Barrel. It was created to improve the development experience by incorporating Vite into Shopify theme development, but theme extensions can also benefit from it.

Its main feature is that scripts built with Vite can be easily used from Liquid. It can also support hot reloading. (Hot reloading scripts is difficult if you simply incorporate Vite.)

A collection of sample projects for Shopify theme extensions is also available.

From here, we will introduce the setup based on the sample project provided by the project.

Installing the Shopify Vite Plugin

Environment

• node: v18.12.0
• npm: v8.19.2 (pnpm or yarn is also fine)

We will proceed on the assumption that you already have a theme extension directory. If you do not have one, create it by referring to the Shopify documentation.

Because we will install packages into a plain theme extension directory (example: extensions/theme-extension), first run npm init.

Next, install the required packages.

npm i -D vite vite vite-plugin-page-reload vite-plugin-shopify

Configuring vite.config.js

Create a vite.config.js file in your theme extension directory.

import { defineConfig } from 'vite'
import pageReload from 'vite-plugin-page-reload'
import shopify from 'vite-plugin-shopify'

export default defineConfig({
  plugins: [
    shopify(),
    pageReload('/tmp/extension.update', {
      delay: 1800,
    }),
  ],
})

.shopifyignore settings

Create a .shopifyignore file in your theme extension directory.

When deploying a theme extension (shopify app deploy), an error will occur if there are directories or files unrelated to the theme extension, so specify the following directories and files to ignore.

assets/*.json
frontend/
node_modules/
package.json
vite.config.js

Try it out

Creating an entry point

1. Create a frontend/entrypoints directory in your theme extension directory
2. Create an entry.js file inside the above directory
3. Write the code to display Hello World in the entry.js file

function listener() {
  const helloWorld = document.createElement('p')
  helloWorld.textContent = 'Hello World'
  document.body.insertBefore(helloWorld, document.body.firstChild)
}

const options = { passive: true, once: true }
document.addEventListener('DOMContentLoaded', listener, options)

call entry point

Add the following to the top of blocks/star_rating.liquid, which already exists in the plain theme extension directory.

{% liquid
  render 'vite-tag' with 'entry.js'
-%}

Preview the theme extension

Run vite in your theme extension directory, then preview the theme extension as usual.

After confirming that Hello World is displayed at the top of the page, let's change the code in entry.js. It is OK if you can confirm that the changes are reflected by hot reloading!

Summary

We introduced how to install the Shopify Vite Plugin with the minimum necessary steps. What did you think?

As the official sample project appears to use Preact, I think it will be very useful when developing medium- to large-scale theme extensions.

We would like to actively adopt it in our apps as well.