vite-plugin-shopify-theme-islands 1.0.0 → 1.0.2

package/dist/index.js

@@ -10,6 +10,42 @@ 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 PREFIX = "[vite-plugin-shopify-theme-islands]";
+function validateOptions(options, directives) {
+  const customDefs = options.directives?.custom ?? [];
+  if (Array.isArray(options.directories) && options.directories.length === 0) {
+    throw new Error(`${PREFIX} "directories" must not be empty`);
+  }
+  const threshold = options.directives?.visible?.threshold;
+  if (threshold !== undefined && (threshold < 0 || threshold > 1)) {
+    throw new Error(`${PREFIX} "directives.visible.threshold" must be between 0 and 1, got ${threshold}`);
+  }
+  if (options.retry !== undefined) {
+    const { retries, delay } = options.retry;
+    if (retries !== undefined && retries < 0) {
+      throw new Error(`${PREFIX} "retry.retries" must be >= 0, got ${retries}`);
+    }
+    if (delay !== undefined && delay < 0) {
+      throw new Error(`${PREFIX} "retry.delay" must be >= 0, got ${delay}`);
+    }
+  }
+  const builtinAttributes = new Set([
+    directives.visible.attribute,
+    directives.idle.attribute,
+    directives.media.attribute,
+    directives.defer.attribute
+  ]);
+  const seen = new Set;
+  for (const def of customDefs) {
+    if (seen.has(def.name)) {
+      throw new Error(`${PREFIX} Duplicate custom directive name: "${def.name}"`);
+    }
+    if (builtinAttributes.has(def.name)) {
+      throw new Error(`${PREFIX} Custom directive "${def.name}" conflicts with a built-in directive`);
+    }
+    seen.add(def.name);
+  }
+}
 var defaults = {
   directories: ["/frontend/js/islands/"],
   directives: {
@@ -71,6 +107,7 @@ function shopifyThemeIslands(options = {}) {
     defer: { ...defaults.directives.defer, ...options.directives?.defer }
   };
   const clientDirectiveDefinitions = options.directives?.custom ?? [];
+  validateOptions(options, directives);
   const debug = options.debug ?? false;
   const log = debug ? (...args) => console.log("[islands]", ...args) : () => {};
   let resolvedDirs = rawDirs;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-shopify-theme-islands",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Vite plugin for island architecture in Shopify themes",
   "type": "module",
   "packageManager": "bun@1.3.10",
@@ -78,11 +78,11 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.4",
-    "@tanstack/intent": "^0.0.19",
+    "@tanstack/intent": "0.0.21",
     "@types/bun": "^1.3.10",
     "@types/node": "^22.0.0",
-    "oxfmt": "^0.40.0",
-    "oxlint": "^1.55.0",
+    "oxfmt": "0.41.0",
+    "oxlint": "1.56.0",
     "typescript": "^5.0.0",
     "vite": "^8.0.0"
   }

package/skills/{vite-plugin-shopify-theme-islands/custom-directives → custom-directives}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: vite-plugin-shopify-theme-islands/custom-directives
+name: custom-directives
 description: >
   Custom client directives registered via directives.custom in vite.config.ts.
   ClientDirective function signature (load, options, el). AND-latch: when
@@ -7,7 +7,7 @@ description: >
   the island activates. Error handling — thrown errors fire islands:error.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.0.0"
+library_version: "1.0.2"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts

package/skills/{vite-plugin-shopify-theme-islands/directives → directives}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: vite-plugin-shopify-theme-islands/directives
+name: directives
 description: >
   Built-in client directives: client:visible (IntersectionObserver, rootMargin),
   client:media (matchMedia query), client:idle (requestIdleCallback),
@@ -7,7 +7,7 @@ description: >
   all must resolve. Per-element value overrides. Empty client:media warning.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.0.0"
+library_version: "1.0.2"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
@@ -165,3 +165,41 @@ Correct:
 The attribute value is passed directly to `IntersectionObserver` as `rootMargin`, fully replacing the global default.
 
 Source: src/runtime.ts — `await visible(el, visibleAttr || rootMargin, threshold, pendingVisible)`
+
+### HIGH Directive attribute typo — island loads without condition
+
+Wrong:
+
+```html
+<product-form client:visibled></product-form>
+<product-form client:Visible></product-form>
+```
+
+Correct:
+
+```html
+<product-form client:visible></product-form>
+```
+
+Directive attributes are case-sensitive. An unrecognised attribute is silently ignored — the island loads immediately as if no directive were set. No warning is emitted. Check for typos if an island activates earlier than expected.
+
+Source: src/runtime.ts — runtime checks exact attribute names from plugin config
+
+### HIGH Agent uses default attribute name when developer has configured a custom one
+
+Wrong:
+
+```html
+<!-- developer has set visible.attribute: "data:visible" in vite.config.ts -->
+<product-form client:visible></product-form>
+```
+
+Correct:
+
+```html
+<product-form data:visible></product-form>
+```
+
+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

package/skills/{vite-plugin-shopify-theme-islands/lifecycle → lifecycle}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: vite-plugin-shopify-theme-islands/lifecycle
+name: lifecycle
 description: >
   Island lifecycle events and SPA teardown. onIslandLoad and onIslandError
   helpers from vite-plugin-shopify-theme-islands/events — prefer these over
@@ -8,7 +8,7 @@ description: >
   module revive for SPA navigation teardown.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.0.0"
+library_version: "1.0.2"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/events.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts

package/skills/{vite-plugin-shopify-theme-islands/setup → setup}/SKILL.md

@@ -1,42 +1,59 @@
 ---
-name: vite-plugin-shopify-theme-islands/setup
+name: setup
 description: >
-  Plugin install and vite.config.ts configuration. Covers shopifyThemeIslands()
-  options: directories (string | string[]), debug, directives deep-merge, and
-  retry (retries, delay with exponential backoff). Load when configuring the
-  plugin, setting island scan directories, or enabling retry.
+  Getting-started journey and plugin configuration. Covers the full path from
+  install to first working island. shopifyThemeIslands() options: directories
+  (string | string[]), debug, directives deep-merge, and retry (retries, delay
+  with exponential backoff). Load when setting up the plugin, configuring
+  island scan directories, or enabling retry.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.0.0"
+library_version: "1.0.2"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/index.ts
 ---
 
 ## Setup
 
+This plugin is framework-agnostic but designed for Shopify themes. Most Shopify
+projects also use
+[vite-plugin-shopify](https://github.com/barrel/vite-plugin-shopify) to handle
+Shopify-specific asset serving — if the project uses it, add this plugin
+alongside it in the existing `plugins` array.
+
+### 1. Add the plugin to `vite.config.ts`
+
 ```ts
 // vite.config.ts
 import { defineConfig } from "vite";
 import shopifyThemeIslands from "vite-plugin-shopify-theme-islands";
 
 export default defineConfig({
-  plugins: [
-    shopifyThemeIslands({
-      directories: ["/frontend/js/islands/"],
-      debug: false,
-      retry: { retries: 2, delay: 500 },
-    }),
-  ],
+  plugins: [shopifyThemeIslands()],
 });
 ```
 
-Import the virtual module in the theme JS entry point to activate islands:
+All options are optional. The default islands directory is `/frontend/js/islands/`.
+
+### 2. Import the virtual module in the theme JS entry point
 
 ```ts
 // frontend/js/theme.ts
 import "vite-plugin-shopify-theme-islands/revive";
 ```
 
+This activates the runtime — islands are never loaded without this import.
+
+### 3. Add directives to Liquid templates
+
+```html
+<!-- sections/product.liquid -->
+<product-form client:visible></product-form>
+```
+
+That's a working setup. Islands in `/frontend/js/islands/` matching the tag
+name are loaded lazily when the directive condition is met.
+
 ## Core Patterns
 
 ### Configure multiple island directories
@@ -101,6 +118,58 @@ The plugin generates the virtual module but has no effect until it is imported i
 
 Source: src/index.ts — VIRTUAL_ID / RESOLVED_ID
 
+### HIGH Agent hardcodes default values — unnecessary noise
+
+Wrong:
+
+```ts
+shopifyThemeIslands({
+  directories: ["/frontend/js/islands/"],
+  debug: false,
+  directives: {
+    visible: { attribute: "client:visible", rootMargin: "200px", threshold: 0 },
+    idle: { attribute: "client:idle", timeout: 500 },
+    media: { attribute: "client:media" },
+    defer: { attribute: "client:defer", delay: 3000 },
+  },
+});
+```
+
+Correct:
+
+```ts
+shopifyThemeIslands();
+```
+
+All options are optional and default to sensible values. Only include options that differ from the defaults.
+
+### HIGH Agent overwrites existing `vite.config.ts` instead of appending
+
+Before adding the plugin, read the existing `vite.config.ts`. Projects commonly
+already have `vite-plugin-shopify` or other plugins — the island plugin must be
+added to the existing `plugins` array, not replace it.
+
+Wrong:
+
+```ts
+// Replaces existing plugins
+export default defineConfig({
+  plugins: [shopifyThemeIslands()],
+});
+```
+
+Correct:
+
+```ts
+// Appends to existing plugins
+export default defineConfig({
+  plugins: [
+    shopify(), // pre-existing plugin preserved
+    shopifyThemeIslands(),
+  ],
+});
+```
+
 ### HIGH `retry` nested inside `directives` — no retries happen
 
 Wrong:

package/skills/{vite-plugin-shopify-theme-islands/writing-islands → writing-islands}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: vite-plugin-shopify-theme-islands/writing-islands
+name: writing-islands
 description: >
   Writing island files. Two discovery modes: directory scanning (files in
   configured directories auto-discovered by tag name = filename) and Island
@@ -8,7 +8,7 @@ description: >
   base class, and child island cascade behaviour.
 type: core
 library: vite-plugin-shopify-theme-islands
-library_version: "1.0.0"
+library_version: "1.0.2"
 sources:
   - Rees1993/vite-plugin-shopify-theme-islands:src/island.ts
   - Rees1993/vite-plugin-shopify-theme-islands:src/runtime.ts