Vite Plugin Shopify Theme Islands

1.3.2 verified Mon Apr 27 auth: no javascript

Island architecture for Shopify themes, lazily hydrating custom elements with loading directives. Current stable version is 1.3.2, released monthly. Ships TypeScript types. Key differentiators: supports both directory scanning and Island mixin patterns, built-in directives (load, visible, idle, media, interaction), runtime events for observability, child island cascade, configurable retry and timeout. Alternative to vanilla Liquid or Shopify's own lazysizes approach.

Common errors

error Cannot find module 'vite-plugin-shopify-theme-islands' or its corresponding type declarations. ↓

cause Missing package installation or incorrect import path.

fix

Run: npm install -D vite-plugin-shopify-theme-islands (or equivalent). Ensure import path is correct (e.g., 'vite-plugin-shopify-theme-islands', not a subpath for main entry).

error The requested module 'vite-plugin-shopify-theme-islands' is a CommonJS module, which may not support all module.exports as named exports. ↓

cause Using require() in a non-CommonJS context or mixing module systems.

fix

Switch to ESM imports: import shopifyThemeIslands from 'vite-plugin-shopify-theme-islands'. Ensure package.json has 'type': 'module'.

error Failed to resolve import "vite-plugin-shopify-theme-islands" from "vite.config.ts". Does the file exist? ↓

cause Plugin not installed or vite.config.ts sits in a directory not covered by node_modules resolution.

fix

Install the package in the same project where vite.config.ts is located. Use a relative path if installing outside the project root.

error Disconnect is not defined ↓

cause Attempting to import { disconnect } from the main package entry instead of the /revive subpath.

fix

Import disconnect from 'vite-plugin-shopify-theme-islands/revive'.

Warnings

breaking Node.js >=22 required. Running on older versions will cause errors. ↓

fix Update Node.js to v22 or later.

breaking Vite >=6 required. Plugin will not work with Vite 5 or earlier. ↓

fix Update Vite to v6 or later.

gotcha Island filenames must contain a hyphen and be lowercase (e.g., product-form.ts not productform.ts). Subdirectories are supported. ↓

fix Rename file to include a hyphen and use lowercase.

deprecated client:interaction directive was introduced in v1.1.0. Prior versions require manual event listeners. ↓

fix Upgrade to v1.1.0+ and use client:interaction attribute instead of custom event binding.

breaking disconnect() must be imported from the /revive subpath, not the main entry. ↓

fix Change import to: import { disconnect } from 'vite-plugin-shopify-theme-islands/revive'

Install

npm install vite-plugin-shopify-theme-islands

yarn add vite-plugin-shopify-theme-islands

pnpm add vite-plugin-shopify-theme-islands

Imports

default

wrong

const shopifyThemeIslands = require('vite-plugin-shopify-theme-islands')

correct

import shopifyThemeIslands from 'vite-plugin-shopify-theme-islands'

Package is ESM-only. CommonJS require will fail.

disconnect

wrong

import { disconnect } from 'vite-plugin-shopify-theme-islands'

correct

import { disconnect } from 'vite-plugin-shopify-theme-islands/revive'

disconnect is exported from the /revive subpath, not the main entry.

Island

wrong

import { Island } from 'vite-plugin-shopify-theme-islands'

correct

import Island from 'vite-plugin-shopify-theme-islands/island'

Island is a default export from the /island subpath, not a named export from the main entry.

InteractionEventName

import type { InteractionEventName } from 'vite-plugin-shopify-theme-islands'

Type import, available from main entry since v1.3.0.

Quickstart

Sets up the plugin, imports the runtime, creates a scanned island, and shows Liquid usage with client:load directive.

// vite.config.ts
import { defineConfig } from 'vite';
import shopifyThemeIslands from 'vite-plugin-shopify-theme-islands';

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

// frontend/entry.js
import 'vite-plugin-shopify-theme-islands/revive';

// frontend/js/islands/product-form.ts
class ProductForm extends HTMLElement {
  connectedCallback() {
    console.log('Product form island hydrated');
  }
}
if (!customElements.get('product-form')) {
  customElements.define('product-form', ProductForm);
}

// In Liquid:
// <product-form client:load></product-form>

// For SPA teardown:
// import { disconnect } from 'vite-plugin-shopify-theme-islands/revive';
// disconnect();