vite-plugin-shopify-theme-islands 0.1.0

package/README.md

@@ -0,0 +1,122 @@
+# vite-plugin-shopify-theme-islands
+
+Island architecture for Shopify themes. Lazily hydrate custom elements using loading directives — only load the JavaScript when it's actually needed.
+
+## Installation
+
+```bash
+bun add -d vite-plugin-shopify-theme-islands
+npm install -D vite-plugin-shopify-theme-islands
+pnpm add -D vite-plugin-shopify-theme-islands
+yarn add -D vite-plugin-shopify-theme-islands
+```
+
+## Setup
+
+### 1. Add the plugin to `vite.config.ts`
+
+```ts
+import { defineConfig } from "vite";
+import shopifyThemeIslands from "vite-plugin-shopify-theme-islands";
+
+export default defineConfig({
+  plugins: [
+    shopifyThemeIslands({
+      pathPrefix: "/frontend/js/islands/",
+    }),
+  ],
+});
+```
+
+### 2. Call `revive` in your entrypoint
+
+```ts
+import revive from "vite-plugin-shopify-theme-islands/revive";
+
+const islands = import.meta.glob("/frontend/js/islands/*.{ts,js}");
+revive(islands);
+```
+
+The glob pattern must match the `pathPrefix` option. Each file in that directory corresponds to a custom element — the filename (without extension) is the tag name.
+
+## Writing islands
+
+Each island is a file in your islands directory that defines and registers a custom element. The filename must match the custom element tag name used in your Liquid templates.
+
+```
+frontend/js/islands/
+  product-form.ts   →  <product-form>
+  cart-drawer.ts    →  <cart-drawer>
+```
+
+```ts
+// frontend/js/islands/product-form.ts
+class ProductForm extends HTMLElement {
+  connectedCallback() {
+    // ...
+  }
+
+  disconnectedCallback() {
+    // ...
+  }
+}
+
+if (!customElements.get("product-form")) {
+  customElements.define("product-form", ProductForm);
+}
+```
+
+## Loading directives
+
+Add these attributes to your custom elements in Liquid to control when the JavaScript loads.
+
+### `client:visible`
+
+Loads the island when the element scrolls into view.
+
+```html
+<product-recommendations client:visible>
+  <!-- ... -->
+</product-recommendations>
+```
+
+### `client:media`
+
+Loads the island when a CSS media query matches.
+
+```html
+<mobile-menu client:media="(max-width: 768px)">
+  <!-- ... -->
+</mobile-menu>
+```
+
+### `client:idle`
+
+Loads the island once the browser is idle (uses `requestIdleCallback`, falls back to `setTimeout`).
+
+```html
+<recently-viewed client:idle>
+  <!-- ... -->
+</recently-viewed>
+```
+
+Directives can be combined — the element will wait for all conditions to be met before loading:
+
+```html
+<heavy-widget client:visible client:idle>
+  <!-- ... -->
+</heavy-widget>
+```
+
+## Options
+
+| Option             | Type     | Default                   | Description                                                    |
+| ------------------ | -------- | ------------------------- | -------------------------------------------------------------- |
+| `pathPrefix`       | `string` | `'/frontend/js/islands/'` | Path prefix used to match `import.meta.glob` keys to tag names |
+| `directiveVisible` | `string` | `'client:visible'`        | Attribute name for the visible directive                       |
+| `directiveMedia`   | `string` | `'client:media'`          | Attribute name for the media directive                         |
+| `directiveIdle`    | `string` | `'client:idle'`           | Attribute name for the idle directive                          |
+
+## License
+
+MIT

package/client.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="vite/client" />
+
+// virtual: alias for Vite convention compatibility
+declare module 'virtual:shopify-theme-islands/revive' {
+  export { default } from 'vite-plugin-shopify-theme-islands/revive';
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import type { Plugin } from 'vite';
+export interface ShopifyThemeIslandsOptions {
+    /** Path prefix used to match island glob keys. Default: `'/frontend/js/islands/'` */
+    pathPrefix?: string;
+    /** Attribute for "load when visible". Default: `'client:visible'` */
+    directiveVisible?: string;
+    /** Attribute for "load when media matches". Default: `'client:media'` */
+    directiveMedia?: string;
+    /** Attribute for "load when idle". Default: `'client:idle'` */
+    directiveIdle?: string;
+}
+export default function shopifyThemeIslands(pluginOptions?: ShopifyThemeIslandsOptions): Plugin;

package/dist/index.js

@@ -0,0 +1,44 @@
+// src/index.ts
+var {readFileSync} = (() => ({}));
+var VIRTUAL_REVIVE = "virtual:shopify-theme-islands/revive";
+var VIRTUAL_RUNTIME = "\x00virtual:shopify-theme-islands/runtime";
+var runtimePath = new URL("./runtime.js", import.meta.url).pathname;
+function shopifyThemeIslands(pluginOptions = {}) {
+  const pathPrefix = pluginOptions.pathPrefix ?? "/frontend/js/islands/";
+  const directiveVisible = pluginOptions.directiveVisible ?? "client:visible";
+  const directiveMedia = pluginOptions.directiveMedia ?? "client:media";
+  const directiveIdle = pluginOptions.directiveIdle ?? "client:idle";
+  const runtime = readFileSync(runtimePath, "utf-8");
+  return {
+    name: "vite-plugin-shopify-theme-islands",
+    enforce: "pre",
+    resolveId(id) {
+      if (id === VIRTUAL_REVIVE || id === "vite-plugin-shopify-theme-islands/revive")
+        return "\x00" + VIRTUAL_REVIVE;
+      if (id === VIRTUAL_RUNTIME)
+        return id;
+      return null;
+    },
+    load(id) {
+      if (id === VIRTUAL_RUNTIME)
+        return runtime;
+      if (id !== "\x00" + VIRTUAL_REVIVE)
+        return null;
+      return `
+import { revive as _revive } from '${VIRTUAL_RUNTIME}';
+
+export default function revive(islands) {
+  _revive(islands, {
+    pathPrefix: ${JSON.stringify(pathPrefix)},
+    directiveVisible: ${JSON.stringify(directiveVisible)},
+    directiveMedia: ${JSON.stringify(directiveMedia)},
+    directiveIdle: ${JSON.stringify(directiveIdle)},
+  });
+}
+`;
+    }
+  };
+}
+export {
+  shopifyThemeIslands as default
+};

package/dist/runtime.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Island architecture runtime for Shopify themes.
+ *
+ * Walks the DOM for custom elements that match island files, then loads them
+ * lazily based on client directives:
+ *
+ *   client:visible  — load when the element scrolls into view
+ *   client:media    — load when a CSS media query matches
+ *   client:idle     — load when the browser has idle time
+ *
+ * Directives can be combined; all conditions must be met before loading.
+ * A MutationObserver re-runs the same logic for elements added dynamically.
+ */
+interface ReviveOptions {
+    pathPrefix?: string;
+    directiveVisible?: string;
+    directiveMedia?: string;
+    directiveIdle?: string;
+}
+export declare function revive(islands: Record<string, () => Promise<unknown>>, options?: ReviveOptions): void;
+export {};

package/dist/runtime.js

@@ -0,0 +1,70 @@
+// src/runtime.ts
+function media(query) {
+  const m = window.matchMedia(query);
+  return new Promise((resolve) => {
+    if (m.matches)
+      resolve();
+    else
+      m.addEventListener("change", () => resolve(), { once: true });
+  });
+}
+function visible(element) {
+  return new Promise((resolve) => {
+    const obs = new IntersectionObserver((entries) => {
+      for (const e of entries) {
+        if (e.isIntersecting) {
+          obs.disconnect();
+          resolve();
+          break;
+        }
+      }
+    });
+    obs.observe(element);
+  });
+}
+function idle() {
+  return new Promise((resolve) => {
+    if ("requestIdleCallback" in window)
+      window.requestIdleCallback(() => resolve());
+    else
+      setTimeout(resolve, 200);
+  });
+}
+function revive(islands, options) {
+  const pathPrefix = options?.pathPrefix ?? "/frontend/js/islands/";
+  const attrVisible = options?.directiveVisible ?? "client:visible";
+  const attrMedia = options?.directiveMedia ?? "client:media";
+  const attrIdle = options?.directiveIdle ?? "client:idle";
+  const observer = new MutationObserver((mutations) => {
+    for (const { addedNodes } of mutations) {
+      for (const node of addedNodes) {
+        if (node.nodeType === Node.ELEMENT_NODE)
+          dfs(node);
+      }
+    }
+  });
+  async function dfs(node) {
+    const tagName = node.tagName.toLowerCase();
+    const loader = islands[pathPrefix + tagName + ".ts"] ?? islands[pathPrefix + tagName + ".js"];
+    if (/-/.test(tagName) && loader) {
+      if (node.hasAttribute(attrVisible))
+        await visible(node);
+      const q = node.getAttribute(attrMedia);
+      if (q)
+        await media(q);
+      if (node.hasAttribute(attrIdle))
+        await idle();
+      loader().catch(console.error);
+    }
+    let child = node.firstElementChild;
+    while (child) {
+      dfs(child);
+      child = child.nextElementSibling;
+    }
+  }
+  dfs(document.body);
+  observer.observe(document.body, { childList: true, subtree: true });
+}
+export {
+  revive
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "vite-plugin-shopify-theme-islands",
+  "version": "0.1.0",
+  "description": "Vite plugin for island architecture in Shopify themes",
+  "type": "module",
+  "packageManager": "bun@1.3.10",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./revive": {
+      "types": "./revive.d.ts"
+    },
+    "./client": {
+      "types": "./client.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "client.d.ts",
+    "revive.d.ts"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "vite",
+    "shopify",
+    "islands",
+    "vite-plugin"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Alex Rees",
+    "email": "alex@thirteenstudios.agency",
+    "url": "https://thirteenstudios.agency"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Rees1993/vite-plugin-shopify-theme-islands"
+  },
+  "homepage": "https://github.com/Rees1993/vite-plugin-shopify-theme-islands#readme",
+  "bugs": {
+    "url": "https://github.com/Rees1993/vite-plugin-shopify-theme-islands/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build:js": "bun build src/index.ts src/runtime.ts --outdir dist --format esm",
+    "build:types": "tsc --declaration --emitDeclarationOnly --outDir dist",
+    "build": "bun run build:js && bun run build:types",
+    "check": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "peerDependencies": {
+    "vite": ">=6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "typescript": "^5.0.0",
+    "vite": "^6.0.0"
+  }
+}

package/revive.d.ts

@@ -0,0 +1,2 @@
+declare function revive(islands: Record<string, () => Promise<unknown>>): void;
+export default revive;