Registry /
web-framework / vite-plugin-shopify-theme-islands
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default
✓ import shopifyThemeIslands from 'vite-plugin-shopify-theme-islands'
✗ const shopifyThemeIslands = require('vite-plugin-shopify-theme-islands')
Package is ESM-only. CommonJS require will fail.
disconnect
✓ import { disconnect } from 'vite-plugin-shopify-theme-islands/revive'
✗ import { disconnect } from 'vite-plugin-shopify-theme-islands'
disconnect is exported from the /revive subpath, not the main entry.
Island
✓ import Island from 'vite-plugin-shopify-theme-islands/island'
✗ import { Island } from 'vite-plugin-shopify-theme-islands'
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.
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();
Errors
Common errors & fixes
Cannot find module 'vite-plugin-shopify-theme-islands' or its corresponding type declarations.
Missing package installation or incorrect import path.
fixRun: 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).
The requested module 'vite-plugin-shopify-theme-islands' is a CommonJS module, which may not support all module.exports as named exports.
Using require() in a non-CommonJS context or mixing module systems.
fixSwitch to ESM imports: import shopifyThemeIslands from 'vite-plugin-shopify-theme-islands'. Ensure package.json has 'type': 'module'.
Failed to resolve import "vite-plugin-shopify-theme-islands" from "vite.config.ts". Does the file exist?
Plugin not installed or vite.config.ts sits in a directory not covered by node_modules resolution.
fixInstall the package in the same project where vite.config.ts is located. Use a relative path if installing outside the project root.
Disconnect is not defined
Attempting to import { disconnect } from the main package entry instead of the /revive subpath.
fixImport disconnect from 'vite-plugin-shopify-theme-islands/revive'.
Audit
Dependencies
viterequiredpeer dependency: requires Vite 6 or newer