{"id":22833,"library":"vite-plugin-shopify-theme-islands","title":"Vite Plugin Shopify Theme Islands","description":"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.","status":"active","version":"1.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/Rees1993/vite-plugin-shopify-theme-islands","tags":["javascript","vite","shopify","islands","vite-plugin","tanstack-intent","typescript"],"install":[{"cmd":"npm install vite-plugin-shopify-theme-islands","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-shopify-theme-islands","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-shopify-theme-islands","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency: requires Vite 6 or newer","package":"vite","optional":false}],"imports":[{"note":"Package is ESM-only. CommonJS require will fail.","wrong":"const shopifyThemeIslands = require('vite-plugin-shopify-theme-islands')","symbol":"default","correct":"import shopifyThemeIslands from 'vite-plugin-shopify-theme-islands'"},{"note":"disconnect is exported from the /revive subpath, not the main entry.","wrong":"import { disconnect } from 'vite-plugin-shopify-theme-islands'","symbol":"disconnect","correct":"import { disconnect } from 'vite-plugin-shopify-theme-islands/revive'"},{"note":"Island is a default export from the /island subpath, not a named export from the main entry.","wrong":"import { Island } from 'vite-plugin-shopify-theme-islands'","symbol":"Island","correct":"import Island from 'vite-plugin-shopify-theme-islands/island'"},{"note":"Type import, available from main entry since v1.3.0.","wrong":"","symbol":"InteractionEventName","correct":"import type { InteractionEventName } from 'vite-plugin-shopify-theme-islands'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport shopifyThemeIslands from 'vite-plugin-shopify-theme-islands';\n\nexport default defineConfig({\n  plugins: [shopifyThemeIslands()],\n});\n\n// frontend/entry.js\nimport 'vite-plugin-shopify-theme-islands/revive';\n\n// frontend/js/islands/product-form.ts\nclass ProductForm extends HTMLElement {\n  connectedCallback() {\n    console.log('Product form island hydrated');\n  }\n}\nif (!customElements.get('product-form')) {\n  customElements.define('product-form', ProductForm);\n}\n\n// In Liquid:\n// <product-form client:load></product-form>\n\n// For SPA teardown:\n// import { disconnect } from 'vite-plugin-shopify-theme-islands/revive';\n// disconnect();","lang":"typescript","description":"Sets up the plugin, imports the runtime, creates a scanned island, and shows Liquid usage with client:load directive."},"warnings":[{"fix":"Update Node.js to v22 or later.","message":"Node.js >=22 required. Running on older versions will cause errors.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Update Vite to v6 or later.","message":"Vite >=6 required. Plugin will not work with Vite 5 or earlier.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Rename file to include a hyphen and use lowercase.","message":"Island filenames must contain a hyphen and be lowercase (e.g., product-form.ts not productform.ts). Subdirectories are supported.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to v1.1.0+ and use client:interaction attribute instead of custom event binding.","message":"client:interaction directive was introduced in v1.1.0. Prior versions require manual event listeners.","severity":"deprecated","affected_versions":"<1.1.0"},{"fix":"Change import to: import { disconnect } from 'vite-plugin-shopify-theme-islands/revive'","message":"disconnect() must be imported from the /revive subpath, not the main entry.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"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).","cause":"Missing package installation or incorrect import path.","error":"Cannot find module 'vite-plugin-shopify-theme-islands' or its corresponding type declarations."},{"fix":"Switch to ESM imports: import shopifyThemeIslands from 'vite-plugin-shopify-theme-islands'. Ensure package.json has 'type': 'module'.","cause":"Using require() in a non-CommonJS context or mixing module systems.","error":"The requested module 'vite-plugin-shopify-theme-islands' is a CommonJS module, which may not support all module.exports as named exports."},{"fix":"Install the package in the same project where vite.config.ts is located. Use a relative path if installing outside the project root.","cause":"Plugin not installed or vite.config.ts sits in a directory not covered by node_modules resolution.","error":"Failed to resolve import \"vite-plugin-shopify-theme-islands\" from \"vite.config.ts\". Does the file exist?"},{"fix":"Import disconnect from 'vite-plugin-shopify-theme-islands/revive'.","cause":"Attempting to import { disconnect } from the main package entry instead of the /revive subpath.","error":"Disconnect is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}