vite-plugin-shopify-theme-islands

Custom client directives registered via directives.custom in vite.config.ts. ClientDirective function signature (load, options, el, ctx). AND-latch: when multiple custom directives match the same element, all must call load() before the island activates. Error handling — thrown errors, rejected promises, and directiveTimeout expiry fire islands:error. Custom directives run after all built-in conditions resolve. Matched directives now receive teardown-aware cleanup via ctx.signal and ctx.onCleanup(). Matching is resolved by src/directive-spine.ts; cleanup, AND-latch, and timeout policy are owned by src/activation-session.ts.

Built-in client directives: client:visible (IntersectionObserver, rootMargin), client:media (matchMedia query), client:idle (requestIdleCallback), client:defer (setTimeout delay), client:interaction (mouseenter/touchstart/focusin). Directives resolve sequentially — visible → media → idle → defer → interaction → custom. Per-element value overrides. Empty client:media warning. `client:idle` and `client:defer` require strict integer strings; invalid values warn and fall back. `client:interaction` validates per-element tokens at runtime: whitespace-only values warn and fall back; mixed supported/unsupported values warn and ignore the unsupported tokens; fully unsupported values warn and fall back to default events. Global `directives.interaction.events` config is intentionally narrowed to the curated set `mouseenter`, `touchstart`, and `focusin`. Implementation: src/directive-spine.ts (gates), src/directive-waiters.ts (built-in waits), src/activation-session.ts (sequencing, custom latch, loader).

Island lifecycle events, subtree helpers, and teardown. onIslandLoad and onIslandError helpers from vite-plugin-shopify-theme-islands/events — prefer these over raw document.addEventListener for guaranteed type safety. Raw DOM events islands:load and islands:error on document. islands:load detail includes tag, duration (ms), and attempt (1-based). islands:error detail includes tag, error, and attempt, including custom directive failures and directiveTimeout expiry. `./revive` now exports scan(), observe(), unobserve(), and disconnect(). disconnect() prevents init from ever starting if called early. Startup, DOM walking, mutation observation, and parent/child activation gating are now owned by src/lifecycle.ts, while subtree/runtime helper coordination is owned by src/runtime-ownership.ts. Event dispatch is via src/runtime-surface.ts; debug-only diagnostics live in src/runtime-observability.ts. Shopify section/block events bridged by default.

Getting-started journey and plugin configuration. Covers the full path from install to first working island. Shopify-first setup: shopifyThemeIslands() options include directories (string | string[]), tagSource ("registeredTag" default — Tag derived from static customElements.define("...", ...) call; "filename" for v1.x compatibility), resolveTag({ filePath, defaultTag }) with unique final-tag requirements (defaultTag is the Registered Tag in registeredTag mode, filename-derived in filename mode), debug, directives deep-merge (visible, idle, media, defer, interaction, custom), retry (retries, delay with exponential backoff), directiveTimeout for hung custom directives, and the curated interaction-event config policy (`mouseenter`, `touchstart`, `focusin`; empty arrays rejected). Per-element `client:interaction` values are runtime-validated against the same curated set: unsupported tokens warn and are ignored; if no supported tokens remain, the runtime falls back to the configured default events.

Writing island files. Two discovery modes: directory scanning (files in configured directories auto-discovered; Tag derived from static customElements.define("...", ...) call by default) and Island mixin (import Island from vite-plugin-shopify-theme-islands/island to mark files anywhere in the project). Mixin islands added or removed during dev invalidate the virtual revive module (reloadModule when available, otherwise a full page reload) — no manual Vite restart. In registeredTag mode (default) Tag ownership comes from the static customElements.define call; filename mode (tagSource: "filename") restores v1.x filename-based ownership. resolveTag overrides run after tag source derivation in both modes. Duplicate final tags fail at compile time. Ordinary implementation edits do not invalidate /revive; only Tag ownership changes do.