vite-plugin-shopify-theme-islands 1.2.0 → 1.2.1

package/dist/config-policy.d.ts

@@ -0,0 +1,11 @@
+import { type ReviveOptions } from "./contract.js";
+import type { ClientDirectiveDefinition, DirectivesConfig, ShopifyThemeIslandsOptions } from "./options.js";
+export interface ResolvedThemeIslandsPolicy {
+    plugin: {
+        directives: DirectivesConfig;
+        customDirectives: ClientDirectiveDefinition[];
+        debug: boolean;
+    };
+    runtime: ReviveOptions;
+}
+export declare function resolveThemeIslandsPolicy(options?: ShopifyThemeIslandsOptions): ResolvedThemeIslandsPolicy;

package/dist/index.d.ts

@@ -1,71 +1,8 @@
+import type { ShopifyThemeIslandsOptions } from "./options.js";
 import type { Plugin } from "vite";
 /** A function that triggers the load of an island module. */
 export type ClientDirectiveLoader = () => Promise<void>;
 export type { ClientDirective, ClientDirectiveOptions } from "./contract.js";
-/** 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). */
-    visible?: {
-        /** HTML attribute name. Default: `'client:visible'` */
-        attribute?: string;
-        /** Passed to IntersectionObserver — loads islands before they scroll into view. Default: `'200px'` */
-        rootMargin?: string;
-        /** Passed to IntersectionObserver — ratio of element that must be visible. Default: `0` */
-        threshold?: number;
-    };
-    /** Configuration for the `client:idle` directive (requestIdleCallback). */
-    idle?: {
-        /** HTML attribute name. Default: `'client:idle'` */
-        attribute?: string;
-        /** Deadline (ms) passed to requestIdleCallback; also used as the setTimeout fallback delay. Default: `500` */
-        timeout?: number;
-    };
-    /** Configuration for the `client:media` directive (matchMedia). */
-    media?: {
-        /** HTML attribute name. Default: `'client:media'` */
-        attribute?: string;
-    };
-    /** Configuration for the `client:defer` directive (fixed setTimeout delay). */
-    defer?: {
-        /** HTML attribute name. Default: `'client:defer'` */
-        attribute?: string;
-        /** Fallback delay (ms) when the attribute has no value. Default: `3000` */
-        delay?: number;
-    };
-    /** Configuration for the `client:interaction` directive (mouseenter/touchstart/focusin). */
-    interaction?: {
-        /** HTML attribute name. Default: `'client:interaction'` */
-        attribute?: string;
-        /** DOM event names to listen for. Default: `['mouseenter', 'touchstart', 'focusin']` */
-        events?: string[];
-    };
-    /** Custom client directives to register. Each entry maps an attribute name to a module entrypoint. */
-    custom?: ClientDirectiveDefinition[];
-}
-/** Event detail and runtime options (single source of truth in contract). */
-import type { RetryConfig } from "./contract.js";
+export type { ClientDirectiveDefinition, DirectivesConfig, ShopifyThemeIslandsOptions, } from "./options.js";
 export type { IslandLoadDetail, IslandErrorDetail, ReviveOptions, RetryConfig, RuntimeDirectivesConfig, } from "./contract.js";
-export interface ShopifyThemeIslandsOptions {
-    /** Directories to scan for island files. Accepts paths or Vite aliases. Default: `['/frontend/js/islands/']` */
-    directories?: string | string[];
-    /** Log discovered islands and generated virtual module. Default: `false` */
-    debug?: boolean;
-    /** Per-directive configuration. */
-    directives?: DirectivesConfig;
-    /** Automatic retry behaviour for failed island loads. */
-    retry?: RetryConfig;
-    /**
-     * Milliseconds before a custom directive that never calls `load()` is considered timed out.
-     * When exceeded, `islands:error` is dispatched and the island is abandoned.
-     * Default: `0` (disabled).
-     */
-    directiveTimeout?: number;
-}
 export default function shopifyThemeIslands(options?: ShopifyThemeIslandsOptions): Plugin;

package/dist/index.js

@@ -54,39 +54,6 @@ function collectTagNames(dir) {
   return names;
 }
 
-// src/revive-module.ts
-function buildReviveModuleSource(params) {
-  const { runtimePath, directoryGlobs, islandPaths, customDirectives, reviveOptions } = params;
-  const directiveImportLines = customDirectives?.map(({ entrypoint }, index) => `import _directive${index} from ${JSON.stringify(entrypoint)};`) ?? [];
-  const globEntries = [
-    `{ ${directoryGlobs.map((glob) => `...import.meta.glob(${JSON.stringify(glob)})`).join(", ")} }`
-  ];
-  if (islandPaths?.length)
-    globEntries.push(`import.meta.glob(${JSON.stringify(islandPaths)})`);
-  const lines = [
-    ...directiveImportLines,
-    `import { revive as _islands } from ${JSON.stringify(runtimePath)};`,
-    `const islands = Object.assign({}, ${globEntries.join(", ")});`,
-    `const options = ${JSON.stringify(reviveOptions)};`
-  ];
-  if (customDirectives?.length) {
-    const customDirectivesMapLines = customDirectives.map(({ name }, index) => `  [${JSON.stringify(name)}, _directive${index}]`);
-    lines.push(`const customDirectives = new Map([
-${customDirectivesMapLines.join(`,
-`)}
-]);`);
-    lines.push(`const payload = { islands, options, customDirectives };`);
-  } else {
-    lines.push(`const payload = { islands, options };`);
-  }
-  lines.push(`export const { disconnect } = _islands(payload);`);
-  return lines.join(`
-`);
-}
-
-// src/index.ts
-import { fileURLToPath } from "node:url";
-
 // src/contract.ts
 var DEFAULT_DIRECTIVES = {
   visible: { attribute: "client:visible", rootMargin: "200px", threshold: 0 },
@@ -137,13 +104,17 @@ function buildIslandMap(payload) {
   return map;
 }
 
-// src/index.ts
-var VIRTUAL_ID = "vite-plugin-shopify-theme-islands/revive";
-var RESOLVED_ID = "\x00" + VIRTUAL_ID;
-var ISLAND_ID = "vite-plugin-shopify-theme-islands/island";
-var runtimePath = fileURLToPath(new URL("./runtime.js", import.meta.url));
-var islandPath = fileURLToPath(new URL("./island.js", import.meta.url));
+// src/config-policy.ts
 var PREFIX = "[vite-plugin-shopify-theme-islands]";
+function mergeDirectives(directives) {
+  return {
+    visible: { ...DEFAULT_DIRECTIVES.visible, ...directives?.visible },
+    idle: { ...DEFAULT_DIRECTIVES.idle, ...directives?.idle },
+    media: { ...DEFAULT_DIRECTIVES.media, ...directives?.media },
+    defer: { ...DEFAULT_DIRECTIVES.defer, ...directives?.defer },
+    interaction: { ...DEFAULT_DIRECTIVES.interaction, ...directives?.interaction }
+  };
+}
 function validateOptions(options, directives) {
   const customDefs = options.directives?.custom ?? [];
   if (Array.isArray(options.directories) && options.directories.length === 0) {
@@ -180,6 +151,93 @@ function validateOptions(options, directives) {
     seen.add(def.name);
   }
 }
+function resolveThemeIslandsPolicy(options = {}) {
+  const directives = mergeDirectives(options.directives);
+  validateOptions(options, directives);
+  const customDirectives = options.directives?.custom ?? [];
+  const debug = options.debug ?? false;
+  const runtime = {
+    directives,
+    debug,
+    ...options.retry !== undefined ? { retry: options.retry } : {},
+    ...options.directiveTimeout !== undefined ? { directiveTimeout: options.directiveTimeout } : {}
+  };
+  return {
+    plugin: {
+      directives,
+      customDirectives,
+      debug
+    },
+    runtime
+  };
+}
+
+// src/revive-module.ts
+function buildReviveModuleSource(params) {
+  const { runtimePath, directoryGlobs, islandPaths, customDirectives, reviveOptions } = params;
+  const directiveImportLines = customDirectives?.map(({ entrypoint }, index) => `import _directive${index} from ${JSON.stringify(entrypoint)};`) ?? [];
+  const globEntries = [
+    `{ ${directoryGlobs.map((glob) => `...import.meta.glob(${JSON.stringify(glob)})`).join(", ")} }`
+  ];
+  if (islandPaths?.length)
+    globEntries.push(`import.meta.glob(${JSON.stringify(islandPaths)})`);
+  const lines = [
+    ...directiveImportLines,
+    `import { revive as _islands } from ${JSON.stringify(runtimePath)};`,
+    `const islands = Object.assign({}, ${globEntries.join(", ")});`,
+    `const options = ${JSON.stringify(reviveOptions)};`
+  ];
+  if (customDirectives?.length) {
+    const customDirectivesMapLines = customDirectives.map(({ name }, index) => `  [${JSON.stringify(name)}, _directive${index}]`);
+    lines.push(`const customDirectives = new Map([
+${customDirectivesMapLines.join(`,
+`)}
+]);`);
+    lines.push(`const payload = { islands, options, customDirectives };`);
+  } else {
+    lines.push(`const payload = { islands, options };`);
+  }
+  lines.push(`export const { disconnect } = _islands(payload);`);
+  return lines.join(`
+`);
+}
+
+// src/revive-bootstrap.ts
+function createReviveBootstrapCompiler(ports, runtimePath) {
+  return {
+    async plan(input) {
+      const islandPaths = input.islandFiles.size > 0 ? ports.toLoadPaths(input.islandFiles, input.root) : null;
+      const customDirectives = input.customDirectives?.length ? await Promise.all(input.customDirectives.map(async ({ name, entrypoint }) => ({
+        name,
+        entrypoint: await ports.resolveEntrypoint(entrypoint)
+      }))) : null;
+      return {
+        runtimePath,
+        directoryGlobs: input.directories.map((dir) => dir + "**/*.{ts,js}"),
+        islandPaths,
+        customDirectives,
+        reviveOptions: input.reviveOptions
+      };
+    },
+    emit(plan) {
+      return buildReviveModuleSource({
+        runtimePath: plan.runtimePath,
+        directoryGlobs: plan.directoryGlobs,
+        islandPaths: plan.islandPaths,
+        customDirectives: plan.customDirectives?.length ? plan.customDirectives : undefined,
+        reviveOptions: plan.reviveOptions
+      });
+    }
+  };
+}
+
+// src/index.ts
+import { fileURLToPath } from "node:url";
+var VIRTUAL_ID = "vite-plugin-shopify-theme-islands/revive";
+var RESOLVED_ID = "\x00" + VIRTUAL_ID;
+var ISLAND_ID = "vite-plugin-shopify-theme-islands/island";
+var runtimePath = fileURLToPath(new URL("./runtime.js", import.meta.url));
+var islandPath = fileURLToPath(new URL("./island.js", import.meta.url));
 var defaultDirectories = ["/frontend/js/islands/"];
 function normalizeDir(dir) {
   return dir.endsWith("/") ? dir : dir + "/";
@@ -198,16 +256,9 @@ function resolveAliases(dirs, config) {
 }
 function shopifyThemeIslands(options = {}) {
   const rawDirs = (Array.isArray(options.directories) ? options.directories : [options.directories ?? defaultDirectories[0]]).map(normalizeDir);
-  const directives = {
-    visible: { ...DEFAULT_DIRECTIVES.visible, ...options.directives?.visible },
-    idle: { ...DEFAULT_DIRECTIVES.idle, ...options.directives?.idle },
-    media: { ...DEFAULT_DIRECTIVES.media, ...options.directives?.media },
-    defer: { ...DEFAULT_DIRECTIVES.defer, ...options.directives?.defer },
-    interaction: { ...DEFAULT_DIRECTIVES.interaction, ...options.directives?.interaction }
-  };
-  const clientDirectiveDefinitions = options.directives?.custom ?? [];
-  validateOptions(options, directives);
-  const debug = options.debug ?? false;
+  const policy = resolveThemeIslandsPolicy(options);
+  const { directives, customDirectives: clientDirectiveDefinitions, debug } = policy.plugin;
+  const { runtime: reviveOptions } = policy;
   const log = debug ? (...args) => console.log("[islands]", ...args) : () => {};
   let resolvedDirs = rawDirs;
   let root = process.cwd();
@@ -284,28 +335,24 @@ function shopifyThemeIslands(options = {}) {
     async load(id) {
       if (id !== RESOLVED_ID)
         return;
-      const directoryGlobs = resolvedDirs.map((dir) => dir + "**/*.{ts,js}");
-      const islandPaths = islandFiles.size > 0 ? getIslandPathsForLoad(islandFiles, root) : null;
-      const customDirectives = [];
-      for (const def of clientDirectiveDefinitions) {
-        const resolved = await this.resolve(def.entrypoint);
-        if (!resolved) {
-          throw new Error(`[vite-plugin-shopify-theme-islands] Cannot resolve custom directive entrypoint: "${def.entrypoint}"`);
-        }
-        customDirectives.push({ name: def.name, entrypoint: resolved.id });
-      }
-      return buildReviveModuleSource({
-        runtimePath,
-        directoryGlobs,
-        islandPaths,
-        customDirectives,
-        reviveOptions: {
-          directives,
-          debug,
-          retry: options.retry,
-          directiveTimeout: options.directiveTimeout
-        }
+      const compiler = createReviveBootstrapCompiler({
+        resolveEntrypoint: async (entrypoint) => {
+          const resolved = await this.resolve(entrypoint);
+          if (!resolved) {
+            throw new Error(`[vite-plugin-shopify-theme-islands] Cannot resolve custom directive entrypoint: "${entrypoint}"`);
+          }
+          return resolved.id;
+        },
+        toLoadPaths: getIslandPathsForLoad
+      }, runtimePath);
+      const plan = await compiler.plan({
+        root,
+        directories: resolvedDirs,
+        islandFiles,
+        customDirectives: clientDirectiveDefinitions,
+        reviveOptions
       });
+      return compiler.emit(plan);
     }
   };
 }

package/dist/options.d.ts

@@ -0,0 +1,64 @@
+import type { RetryConfig } from "./contract.js";
+/** 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). */
+    visible?: {
+        /** HTML attribute name. Default: `'client:visible'` */
+        attribute?: string;
+        /** Passed to IntersectionObserver — loads islands before they scroll into view. Default: `'200px'` */
+        rootMargin?: string;
+        /** Passed to IntersectionObserver — ratio of element that must be visible. Default: `0` */
+        threshold?: number;
+    };
+    /** Configuration for the `client:idle` directive (requestIdleCallback). */
+    idle?: {
+        /** HTML attribute name. Default: `'client:idle'` */
+        attribute?: string;
+        /** Deadline (ms) passed to requestIdleCallback; also used as the setTimeout fallback delay. Default: `500` */
+        timeout?: number;
+    };
+    /** Configuration for the `client:media` directive (matchMedia). */
+    media?: {
+        /** HTML attribute name. Default: `'client:media'` */
+        attribute?: string;
+    };
+    /** Configuration for the `client:defer` directive (fixed setTimeout delay). */
+    defer?: {
+        /** HTML attribute name. Default: `'client:defer'` */
+        attribute?: string;
+        /** Fallback delay (ms) when the attribute has no value. Default: `3000` */
+        delay?: number;
+    };
+    /** Configuration for the `client:interaction` directive (mouseenter/touchstart/focusin). */
+    interaction?: {
+        /** HTML attribute name. Default: `'client:interaction'` */
+        attribute?: string;
+        /** DOM event names to listen for. Default: `['mouseenter', 'touchstart', 'focusin']` */
+        events?: string[];
+    };
+    /** 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/']` */
+    directories?: string | string[];
+    /** Log discovered islands and generated virtual module. Default: `false` */
+    debug?: boolean;
+    /** Per-directive configuration. */
+    directives?: DirectivesConfig;
+    /** Automatic retry behaviour for failed island loads. */
+    retry?: RetryConfig;
+    /**
+     * Milliseconds before a custom directive that never calls `load()` is considered timed out.
+     * When exceeded, `islands:error` is dispatched and the island is abandoned.
+     * Default: `0` (disabled).
+     */
+    directiveTimeout?: number;
+}

package/dist/revive-bootstrap.d.ts

@@ -0,0 +1,31 @@
+import type { ReviveOptions } from "./contract.js";
+export interface ResolvedCustomDirective {
+    name: string;
+    entrypoint: string;
+}
+export interface ReviveBootstrapInputs {
+    root: string;
+    directories: string[];
+    islandFiles: Set<string>;
+    customDirectives?: Array<{
+        name: string;
+        entrypoint: string;
+    }>;
+    reviveOptions: ReviveOptions;
+}
+export interface ReviveBootstrapPlan {
+    runtimePath: string;
+    directoryGlobs: string[];
+    islandPaths: string[] | null;
+    customDirectives: ResolvedCustomDirective[] | null;
+    reviveOptions: ReviveOptions;
+}
+export interface ReviveBootstrapCompilerPorts {
+    resolveEntrypoint(entrypoint: string): Promise<string>;
+    toLoadPaths(islandFiles: Set<string>, root: string): string[];
+}
+export interface ReviveBootstrapCompiler {
+    plan(input: ReviveBootstrapInputs): Promise<ReviveBootstrapPlan>;
+    emit(plan: ReviveBootstrapPlan): string;
+}
+export declare function createReviveBootstrapCompiler(ports: ReviveBootstrapCompilerPorts, runtimePath: string): ReviveBootstrapCompiler;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-shopify-theme-islands",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Vite plugin for island architecture in Shopify themes",
   "type": "module",
   "packageManager": "bun@1.3.10",

package/skills/custom-directives/SKILL.md

@@ -9,11 +9,12 @@ description: >
   built-in conditions resolve.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.2.0"
+library_version: "1.2.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/config-policy.ts
 ---
 
 ## Setup
@@ -222,7 +223,7 @@ shopifyThemeIslands({
 
 Custom directive names must be unique and must not collide with any built-in directive name, including renamed built-ins.
 
-Source: src/index.ts — validateOptions duplicate and built-in conflict checks
+Source: src/config-policy.ts — validateOptions() duplicate and built-in conflict checks
 
 ### HIGH Entrypoint path missing `./` prefix
 

package/skills/directives/SKILL.md

@@ -9,10 +9,11 @@ description: >
   client:interaction values warn and fall back to default events.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.2.0"
+library_version: "1.2.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/options.ts
 ---
 
 ## Setup
@@ -261,4 +262,4 @@ Correct:
 
 When `directives.visible.attribute` (or any directive's `attribute` option) is overridden in `vite.config.ts`, all Liquid templates must use the configured name. The default `client:*` names no longer apply. Always read `vite.config.ts` to check for overridden attribute names before writing directives in Liquid.
 
-Source: src/index.ts:DirectivesConfig — `attribute` field per directive; src/runtime.ts reads configured attribute names at runtime
+Source: src/options.ts:DirectivesConfig — `attribute` field per directive; src/runtime.ts reads configured attribute names at runtime

package/skills/lifecycle/SKILL.md

@@ -11,11 +11,12 @@ description: >
   teardown.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.2.0"
+library_version: "1.2.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/events.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/revive-module.ts
 ---
 
 ## Setup
@@ -144,7 +145,7 @@ import { disconnect } from "vite-plugin-shopify-theme-islands/revive";
 
 Only the virtual module (`/revive`) exports the `disconnect` bound to the plugin-managed `revive()` instance. Importing from other entry points references a different or nonexistent instance.
 
-Source: src/index.ts — virtual module `export const { disconnect } = _islands(...)`
+Source: src/revive-module.ts — buildReviveModuleSource() emits `export const { disconnect } = _islands(payload)`
 
 ### MEDIUM `onIslandError` fires on every retry, not just final failure
 

package/skills/setup/SKILL.md

@@ -10,10 +10,12 @@ description: >
   directive timeout.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.2.0"
+library_version: "1.2.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/contract.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/options.ts
+  - Rees1993/vite-plugin-shopify-theme-islands:src/config-policy.ts
 ---
 
 ## Setup
@@ -207,7 +209,7 @@ shopifyThemeIslands({
 
 `directives` accepts only `visible`, `idle`, `media`, `defer`, `interaction`, and `custom`. `retry` at `directives.retry` is silently ignored.
 
-Source: src/index.ts — ShopifyThemeIslandsOptions
+Source: src/options.ts — ShopifyThemeIslandsOptions
 
 ### HIGH Wrong key name for retry count
 
@@ -250,4 +252,4 @@ shopifyThemeIslands({
 
 `directiveTimeout` is a top-level plugin option, not part of the per-directive config object.
 
-Source: src/index.ts — ShopifyThemeIslandsOptions
+Source: src/options.ts — ShopifyThemeIslandsOptions

package/skills/writing-islands/SKILL.md

@@ -8,7 +8,7 @@ description: >
   base class, and child island cascade behaviour.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.2.0"
+library_version: "1.2.1"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/island.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/discovery.ts