vite-plugin-shopify-theme-islands 0.5.0 → 0.6.1

package/README.md

@@ -100,7 +100,7 @@ The plugin detects the mixin import at build time and includes the file as a laz
 
 Both can be used together — directory scanning for new islands, the mixin for existing components you want to adopt without moving.
 
-## Loading directives
+## Directives
 
 Add these attributes to your custom elements in Liquid to control when the JavaScript loads. Without a directive, the island loads immediately.
 
@@ -114,6 +114,15 @@ Loads the island when the element scrolls into view.
 </product-recommendations>
 ```
 
+The attribute value overrides the global `rootMargin` for that element only:
+
+```html
+<!-- load only once fully visible (no pre-load margin) -->
+<product-recommendations client:visible="0px">
+  <!-- ... -->
+</product-recommendations>
+```
+
 ### `client:media`
 
 Loads the island when a CSS media query matches.
@@ -134,6 +143,15 @@ Loads the island once the browser is idle (uses `requestIdleCallback` with a 500
 </recently-viewed>
 ```
 
+The attribute value overrides the global `timeout` for that element only:
+
+```html
+<!-- wait up to 2 seconds for idle time before loading -->
+<recently-viewed client:idle="2000">
+  <!-- ... -->
+</recently-viewed>
+```
+
 ### `client:defer`
 
 Loads the island after a fixed delay. The delay in milliseconds is read from the attribute value. If no value is given, the configured default (3000ms) is used.
@@ -151,7 +169,9 @@ Loads the island after a fixed delay. The delay in milliseconds is read from the
 
 Unlike `client:idle`, which waits for genuine browser idle time, `client:defer` always waits exactly the specified number of milliseconds.
 
-Directives can be combined — the element will wait for all conditions to be met before loading:
+### Combining directives
+
+Directives can be combined — the element waits for all conditions to be met before loading:
 
 ```html
 <heavy-widget client:visible client:idle>
@@ -159,13 +179,83 @@ Directives can be combined — the element will wait for all conditions to be me
 </heavy-widget>
 ```
 
-## Options
+### Custom directives
+
+Register your own loading conditions via `directives.custom`. A custom directive is a function that receives a `load` callback and decides when to call it.
+
+#### 1. Write the directive
+
+```ts
+// src/directives/hover.ts
+import type { ClientDirective } from "vite-plugin-shopify-theme-islands";
+
+const hoverDirective: ClientDirective = (load, _opts, el) => {
+  el.addEventListener("mouseenter", load, { once: true });
+};
+
+export default hoverDirective;
+```
+
+`mouseenter` fires before `click`, so the module starts downloading the moment the user moves their cursor toward the element — by the time they click it's already loaded.
+
+The function signature is `(load, options, el) => void | Promise<void>`:
+
+| Parameter       | Type                     | Description                                           |
+| --------------- | ------------------------ | ----------------------------------------------------- |
+| `load`          | `() => Promise<unknown>` | Call this to trigger the island module load           |
+| `options.name`  | `string`                 | The matched attribute name, e.g. `'client:hover'`     |
+| `options.value` | `string`                 | The attribute value; empty string if no value was set |
+| `el`            | `HTMLElement`            | The island element                                    |
+
+#### 2. Register it in the plugin config
+
+```ts
+// vite.config.ts
+import shopifyThemeIslands from "vite-plugin-shopify-theme-islands";
+
+export default defineConfig({
+  plugins: [
+    shopifyThemeIslands({
+      directives: {
+        custom: [{ name: "client:hover", entrypoint: "./src/directives/hover.ts" }],
+      },
+    }),
+  ],
+});
+```
+
+The `entrypoint` supports Vite aliases.
+
+#### 3. Use it in Liquid
+
+```html
+<quick-add client:hover>
+  <!-- ... -->
+</quick-add>
+```
+
+#### Ordering
+
+Built-in directives always run first. A custom directive is only invoked after all built-in conditions on the element have been met. This means you can gate a custom directive behind `client:visible` to avoid wiring event listeners for off-screen elements:
+
+```html
+<!-- element must enter the viewport before the hover handler is registered -->
+<quick-add client:visible client:hover>
+  <!-- ... -->
+</quick-add>
+```
+
+The custom directive owns the `load()` call — the built-in chain never calls it directly when a custom directive is matched.
+
+> Only one custom directive can be active per element. If multiple custom directive attributes are present, the first registered one is used and a console warning is emitted. Combining multiple custom directives on one element is not yet supported.
+
+## Configuration
 
-| Option        | Type                 | Default                     | Description                                                                         |
-| ------------- | -------------------- | --------------------------- | ----------------------------------------------------------------------------------- |
-| `directories` | `string \| string[]` | `['/frontend/js/islands/']` | Directories to scan for island files. Accepts Vite aliases.                         |
-| `directives`  | `object`             | see below                   | Per-directive configuration. Each directive has an `attribute` name and extra options. |
-| `debug`       | `boolean`            | `false`                     | Log discovered islands at build time and directive events in the browser console.   |
+| Option        | Type                 | Default                     | Description                                                                        |
+| ------------- | -------------------- | --------------------------- | ---------------------------------------------------------------------------------- |
+| `directories` | `string \| string[]` | `['/frontend/js/islands/']` | Directories to scan for island files. Accepts Vite aliases.                        |
+| `directives`  | `object`             | see below                   | Per-directive configuration — attribute names, timing options, and custom entries. |
+| `debug`       | `boolean`            | `false`                     | Log discovered islands at build time and directive events in the browser console.  |
 
 ### Directive defaults
 
@@ -174,20 +264,21 @@ shopifyThemeIslands({
   directives: {
     visible: {
       attribute: "client:visible", // HTML attribute name
-      rootMargin: "200px",         // passed to IntersectionObserver — pre-loads before scrolling into view
-      threshold: 0,                // passed to IntersectionObserver — ratio of element that must be visible
+      rootMargin: "200px", // passed to IntersectionObserver — pre-loads before scrolling into view
+      threshold: 0, // passed to IntersectionObserver — ratio of element that must be visible
     },
     idle: {
-      attribute: "client:idle",    // HTML attribute name
-      timeout: 500,                // deadline (ms) for requestIdleCallback; also the setTimeout fallback delay
+      attribute: "client:idle", // HTML attribute name
+      timeout: 500, // deadline (ms) for requestIdleCallback; also the setTimeout fallback delay
     },
     media: {
-      attribute: "client:media",   // HTML attribute name
+      attribute: "client:media", // HTML attribute name
     },
     defer: {
-      attribute: "client:defer",   // HTML attribute name
-      delay: 3000,                 // fallback delay (ms) when the attribute has no value
+      attribute: "client:defer", // HTML attribute name
+      delay: 3000, // fallback delay (ms) when the attribute has no value
     },
+    custom: [], // custom directives — see Custom directives above
   },
 });
 ```

package/dist/index.d.ts

@@ -1,4 +1,48 @@
 import type { Plugin } from "vite";
+/** A function that triggers the load of an island module. */
+export type ClientDirectiveLoader = () => Promise<unknown>;
+/** Options passed to a custom client directive function. */
+export interface ClientDirectiveOptions {
+    /** The matched attribute name, e.g. `'client:on-click'` */
+    name: string;
+    /** The attribute value; empty string if no value was set */
+    value: string;
+}
+/**
+ * A custom client directive function.
+ *
+ * Called by the runtime when a matching attribute is found on an island element.
+ * The function is responsible for calling `load()` when the desired condition is met.
+ *
+ * @example
+ * ```ts
+ * // src/directives/hover.ts
+ * import type { ClientDirective } from 'vite-plugin-shopify-theme-islands';
+ *
+ * const hoverDirective: ClientDirective = (load, _opts, el) => {
+ *   el.addEventListener('mouseenter', load, { once: true });
+ * };
+ *
+ * export default hoverDirective;
+ * ```
+ *
+ * Register it in `vite.config.ts`:
+ * ```ts
+ * shopifyThemeIslands({
+ *   directives: {
+ *     custom: [{ name: 'client:hover', entrypoint: './src/directives/hover.ts' }],
+ *   },
+ * })
+ * ```
+ */
+export type ClientDirective = (load: ClientDirectiveLoader, options: ClientDirectiveOptions, el: HTMLElement) => void | Promise<void>;
+/** Plugin option entry for registering a custom client directive. */
+export interface ClientDirectiveDefinition {
+    /** HTML attribute name, e.g. `'client:on-click'` */
+    name: string;
+    /** Path to the directive module (supports Vite aliases) */
+    entrypoint: string;
+}
 /** Shared directive configuration shape used by both the plugin and the runtime. */
 export interface DirectivesConfig {
     /** Configuration for the `client:visible` directive (IntersectionObserver). */
@@ -29,6 +73,8 @@ export interface DirectivesConfig {
         /** Fallback delay (ms) when the attribute has no value. Default: `3000` */
         delay?: number;
     };
+    /** Custom client directives to register. Each entry maps an attribute name to a module entrypoint. */
+    custom?: ClientDirectiveDefinition[];
 }
 export interface ShopifyThemeIslandsOptions {
     /** Directories to scan for island files. Accepts paths or Vite aliases. Default: `['/frontend/js/islands/']` */

package/dist/index.js

@@ -9,6 +9,7 @@ var runtimePath = fileURLToPath(new URL("./runtime.js", import.meta.url));
 var islandPath = fileURLToPath(new URL("./island.js", import.meta.url));
 var ISLAND_IMPORT_RE = /from\s+['"]vite-plugin-shopify-theme-islands\/island['"]/;
 var TS_JS_RE = /\.(ts|js)$/;
+var SKIP_DIRS = new Set(["node_modules", "dist", "build", "public", "assets", ".cache"]);
 var defaults = {
   directories: ["/frontend/js/islands/"],
   directives: {
@@ -33,6 +34,23 @@ function resolveAliases(dirs, config) {
     return dir;
   });
 }
+function collectTagNames(dir, names) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name))
+      continue;
+    if (entry.isDirectory()) {
+      collectTagNames(join(dir, entry.name), names);
+    } else if (TS_JS_RE.test(entry.name)) {
+      names.push(entry.name.replace(/\.(ts|js)$/, ""));
+    }
+  }
+}
 function scanForIslandFiles(dir, found) {
   let entries;
   try {
@@ -41,7 +59,7 @@ function scanForIslandFiles(dir, found) {
     return;
   }
   for (const entry of entries) {
-    if (entry.name.startsWith(".") || entry.name === "node_modules")
+    if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name))
       continue;
     const full = join(dir, entry.name);
     if (entry.isDirectory()) {
@@ -63,46 +81,51 @@ function shopifyThemeIslands(options = {}) {
     media: { ...defaults.directives.media, ...options.directives?.media },
     defer: { ...defaults.directives.defer, ...options.directives?.defer }
   };
+  const clientDirectiveDefinitions = options.directives?.custom ?? [];
   const debug = options.debug ?? false;
-  const log = (...args) => {
-    if (debug)
-      console.log("[islands]", ...args);
-  };
+  const log = debug ? (...args) => console.log("[islands]", ...args) : () => {};
   let resolvedDirs = rawDirs;
   let root = process.cwd();
+  let absDirs = rawDirs;
   const islandFiles = new Set;
   let scanned = false;
-  const inDirectory = (file) => resolvedDirs.some((dir) => {
-    const absDir = dir.startsWith(root) ? dir : join(root, dir.replace(/^\//, ""));
-    return file.startsWith(absDir);
-  });
+  const inDirectory = (file) => absDirs.some((dir) => file.startsWith(dir));
   return {
     name: "vite-plugin-shopify-theme-islands",
     enforce: "pre",
     configResolved(config) {
       root = config.root;
       resolvedDirs = resolveAliases(rawDirs, config);
+      absDirs = resolvedDirs.map((d) => d.startsWith(root) ? d : join(root, d.replace(/^\//, "")));
     },
     buildStart() {
       if (scanned)
         return;
       scanned = true;
+      const t0 = performance.now();
       scanForIslandFiles(root, islandFiles);
+      const scanMs = (performance.now() - t0).toFixed(1);
       for (const f of islandFiles)
         if (inDirectory(f))
           islandFiles.delete(f);
       if (debug) {
+        log(`Scanned in ${scanMs}ms`);
         log("Scanning directories:", resolvedDirs.map((d) => d + "**/*.{ts,js}").join(", "));
-        log("Directives:", directives);
+        const dirNames = [];
+        for (const dir of absDirs)
+          collectTagNames(dir, dirNames);
+        if (dirNames.length)
+          log(`Found ${dirNames.length} directory island(s): [${dirNames.join(", ")}]`);
         if (islandFiles.size) {
           log(`Found ${islandFiles.size} island file(s) via mixin import:`);
           for (const f of islandFiles)
             log(" ", relative(root, f));
         }
+        log("Directives:", directives);
       }
     },
     transform(code, id) {
-      if (!id.endsWith(".ts") && !id.endsWith(".js"))
+      if (!TS_JS_RE.test(id))
         return;
       if (code.includes("shopify-theme-islands/island") && ISLAND_IMPORT_RE.test(code) && !inDirectory(id)) {
         islandFiles.add(id);
@@ -137,21 +160,40 @@ function shopifyThemeIslands(options = {}) {
       if (id === ISLAND_ID)
         return islandPath;
     },
-    load(id) {
+    async load(id) {
       if (id !== RESOLVED_ID)
         return;
       const globs = resolvedDirs.map((dir) => `...import.meta.glob(${JSON.stringify(dir + "**/*.{ts,js}")})`);
-      const islandPaths = [...islandFiles].map((file) => "/" + relative(root, file).replace(/\\/g, "/"));
-      const islandsEntries = [
-        globs.length ? `{ ${globs.join(", ")} }` : null,
-        islandFiles.size ? `import.meta.glob(${JSON.stringify(islandPaths)})` : null
-      ].filter(Boolean);
-      return [
+      const islandPaths = islandFiles.size ? [...islandFiles].map((file) => "/" + relative(root, file).replace(/\\/g, "/")) : null;
+      const islandsEntries = [`{ ${globs.join(", ")} }`];
+      if (islandPaths)
+        islandsEntries.push(`import.meta.glob(${JSON.stringify(islandPaths)})`);
+      const directiveImports = [];
+      const mapEntries = [];
+      for (const [i, def] of clientDirectiveDefinitions.entries()) {
+        const resolved = await this.resolve(def.entrypoint);
+        if (!resolved) {
+          throw new Error(`[vite-plugin-shopify-theme-islands] Cannot resolve custom directive entrypoint: "${def.entrypoint}"`);
+        }
+        directiveImports.push(`import _directive${i} from ${JSON.stringify(resolved.id)};`);
+        mapEntries.push(`  [${JSON.stringify(def.name)}, _directive${i}]`);
+      }
+      const lines = [
+        ...directiveImports,
         `import { revive as _islands } from ${JSON.stringify(runtimePath)};`,
         `const islands = Object.assign({}, ${islandsEntries.join(", ")});`,
-        `const options = ${JSON.stringify({ directives, debug })};`,
-        `_islands(islands, options);`
-      ].join(`
+        `const options = ${JSON.stringify({ directives, debug })};`
+      ];
+      if (mapEntries.length) {
+        lines.push(`const customDirectives = new Map([
+${mapEntries.join(`,
+`)}
+]);`);
+        lines.push(`_islands(islands, options, customDirectives);`);
+      } else {
+        lines.push(`_islands(islands, options);`);
+      }
+      return lines.join(`
 `);
     }
   };

package/dist/runtime.d.ts

@@ -12,5 +12,5 @@
  * Directives can be combined; all conditions must be met before loading.
  * A MutationObserver re-runs the same logic for elements added dynamically.
  */
-import type { ReviveOptions } from "./index.js";
-export declare function revive(islands: Record<string, () => Promise<unknown>>, options?: ReviveOptions): void;
+import type { ClientDirective, ReviveOptions } from "./index.js";
+export declare function revive(islands: Record<string, () => Promise<unknown>>, options?: ReviveOptions, customDirectives?: Map<string, ClientDirective>): void;

package/dist/runtime.js

@@ -41,7 +41,7 @@ function idle(timeout) {
 var customElementFilter = {
   acceptNode: (node) => node.tagName.includes("-") ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP
 };
-function revive(islands, options) {
+function revive(islands, options, customDirectives) {
   const attrVisible = options?.directives?.visible?.attribute ?? "client:visible";
   const attrMedia = options?.directives?.media?.attribute ?? "client:media";
   const attrIdle = options?.directives?.idle?.attribute ?? "client:idle";
@@ -50,7 +50,8 @@ function revive(islands, options) {
   const threshold = options?.directives?.visible?.threshold ?? 0;
   const idleTimeout = options?.directives?.idle?.timeout ?? 500;
   const deferDelay = options?.directives?.defer?.delay ?? 3000;
-  const log = options?.debug ? (...args) => console.debug("[islands]", ...args) : () => {};
+  const debug = options?.debug ?? false;
+  const log = debug ? (...args) => console.log("[islands]", ...args) : () => {};
   const islandMap = new Map;
   for (const [key, loader] of Object.entries(islands)) {
     const tagName = key.split("/").pop().replace(/\.(ts|js)$/, "");
@@ -61,44 +62,79 @@ function revive(islands, options) {
     if (!islandMap.has(tagName))
       islandMap.set(tagName, loader);
   }
+  log(`revive() ready — ${islandMap.size} island(s)`);
   const queued = new Set;
   const pendingVisible = new Map;
   async function loadIsland(tagName, el, loader) {
     log(`<${tagName}> activating`);
+    const msgs = [];
+    const note = debug ? (msg) => {
+      msgs.push(msg);
+    } : () => {};
+    const flush = debug ? (final) => {
+      if (msgs.length === 0) {
+        console.log("[islands]", `<${tagName}> ${final}`);
+      } else {
+        console.groupCollapsed(`[islands] <${tagName}>`);
+        for (const m of msgs)
+          console.log(m);
+        console.log(final);
+        console.groupEnd();
+      }
+    } : () => {};
     try {
       if (el.hasAttribute(attrVisible)) {
-        log(`<${tagName}> waiting for ${attrVisible}`);
-        await visible(el, rootMargin, threshold, pendingVisible);
-        log(`<${tagName}> ${attrVisible} resolved`);
+        const elRootMargin = el.getAttribute(attrVisible) || rootMargin;
+        note(`waiting for ${attrVisible}`);
+        await visible(el, elRootMargin, threshold, pendingVisible);
       }
-      const q = el.getAttribute(attrMedia);
-      if (q) {
-        log(`<${tagName}> waiting for ${attrMedia}="${q}"`);
-        await media(q);
-        log(`<${tagName}> ${attrMedia} resolved`);
+      const query = el.getAttribute(attrMedia);
+      if (query) {
+        note(`waiting for ${attrMedia}="${query}"`);
+        await media(query);
       }
       if (el.hasAttribute(attrIdle)) {
-        log(`<${tagName}> waiting for ${attrIdle} (timeout: ${idleTimeout}ms)`);
-        await idle(idleTimeout);
-        log(`<${tagName}> ${attrIdle} resolved`);
+        const rawIdle = parseInt(el.getAttribute(attrIdle), 10);
+        const elTimeout = Number.isNaN(rawIdle) ? idleTimeout : rawIdle;
+        note(`waiting for ${attrIdle} (timeout: ${elTimeout}ms)`);
+        await idle(elTimeout);
       }
       const d = el.getAttribute(attrDefer);
       if (d !== null) {
         const raw = parseInt(d, 10);
-        const ms = d === "" || Number.isNaN(raw) ? deferDelay : raw;
+        const ms = Number.isNaN(raw) ? deferDelay : raw;
         if (d !== "" && Number.isNaN(raw)) {
           console.warn(`[islands] <${tagName}> invalid ${attrDefer} value "${d}" — using default ${deferDelay}ms`);
         }
-        log(`<${tagName}> waiting for ${attrDefer} (${ms}ms)`);
+        note(`waiting for ${attrDefer} (${ms}ms)`);
         await defer(ms);
-        log(`<${tagName}> ${attrDefer} resolved`);
       }
     } catch {
-      log(`<${tagName}> aborted (element removed)`);
+      flush("aborted (element removed)");
       return;
     }
-    log(`<${tagName}> loading`);
-    loader().catch((err) => console.error(`[islands] Failed to load <${tagName}>:`, err));
+    const run = () => loader().catch((err) => {
+      console.error(`[islands] Failed to load <${tagName}>:`, err);
+      queued.delete(tagName);
+    });
+    if (customDirectives?.size) {
+      const matched = [];
+      for (const [attrName, directiveFn] of customDirectives) {
+        if (el.hasAttribute(attrName))
+          matched.push([attrName, directiveFn]);
+      }
+      if (matched.length > 1) {
+        console.warn(`[islands] <${tagName}> has multiple custom directives (${matched.map(([a]) => a).join(", ")}) — only "${matched[0][0]}" will be used. Combining custom directives is not yet supported.`);
+      }
+      if (matched.length > 0) {
+        const [attrName, directiveFn] = matched[0];
+        flush(`dispatching to custom directive ${attrName}`);
+        directiveFn(run, { name: attrName, value: el.getAttribute(attrName) }, el);
+        return;
+      }
+    }
+    flush("triggered");
+    run();
   }
   function activate(el) {
     const tagName = el.tagName.toLowerCase();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-shopify-theme-islands",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Vite plugin for island architecture in Shopify themes",
   "type": "module",
   "packageManager": "bun@1.3.10",
@@ -58,7 +58,9 @@
     "test:plugin": "bun test src/__tests__/plugin.test.ts",
     "test:runtime": "bun test ./src/__tests__/runtime.test.ts",
     "test": "bun test",
-    "test:watch": "bun test --watch"
+    "test:watch": "bun test --watch",
+    "lint": "oxlint src/",
+    "format": "oxfmt src/"
   },
   "peerDependencies": {
     "vite": ">=6"
@@ -67,6 +69,8 @@
     "@happy-dom/global-registrator": "^20.8.3",
     "@types/bun": "latest",
     "@types/node": "^25.3.3",
+    "oxfmt": "^0.38.0",
+    "oxlint": "^1.53.0",
     "typescript": "^5.0.0",
     "vite": "^6.0.0"
   }