keen_phoenix_svelte

Auto-mount compiled Svelte apps into Phoenix — on both LiveView and plain controller-rendered pages — as self-contained islands.

Write this in a template:

<.svelte name="like" id={"like-#{@id}"} props={%{id: @id, liked: @liked}} />

…and the compiled Svelte app in assets/apps/like/ is mounted into that element, kept in sync with server state, given a context/api/channel/live bridge to the server (plus a bus for island-to-island messaging), and torn down on navigation — no manual <script>/<link> wiring. A configurable placeholder shows while the bundle loads (server-wide default, per-app <:placeholder> override), so there's no flash of empty container.

Svelte is the first-class, tooled path, but the mount boundary is framework-neutral — an island's entry just default-exports (target, opts) => { setProps, destroy }. Because every island mounts through that one contract, there's a single component, <.app> (an optional framework="…" attribute just tags data-framework for debugging). The demo mounts Svelte, Lit, React and vanilla-JS islands through it. <.svelte> remains as a back-compat alias.

New here, or comparing this to live_svelte? Start with Philosophy & comparison — the autonomous-island model, what this deliberately doesn't do, and how it differs from live_svelte.

What's New in v1.0.0-rc.2

• Framework-neutral <.app> — one component mounts any island — Every island mounts through the same (target, opts) => { setProps, destroy } contract, so there is now a single app/1 component regardless of whether the bundle is Svelte, Lit, React, or hand-written vanilla JS. An optional framework attribute just emits an informational data-framework tag. <.svelte> remains as a back-compat alias for the rc.1 name.
• Placeholder / loader — no flash of empty container — <.app> renders a placeholder that the client clears the instant the bundle mounts (after the fetch, so it stays visible the whole time). Resolution is a per-call <:placeholder> slot › the server-wide config :keen_phoenix_svelte, :placeholder › a built-in, dependency-free skeleton. The server default accepts an HTML string, a function, {mod, fun}, or false to disable.
• Event bus — island-to-island messaging without the server — A bus joins the app boundary: a page-wide, client-side pub/sub (emit/on/once) over a DOM EventTarget, wired into both the LiveView hook and mountStatic(), so independent islands coordinate without a round-trip and without importing each other.
• External apps — a registry with :direct/:proxy delivery — KeenPhoenixSvelte.Apps registers islands whose bundle lives elsewhere (a CDN, another deploy); <.runtime> emits a name → url manifest and AppsManager.resolve/1 loads them. Pick :direct (browser imports the CDN URL) or :proxy (Phoenix fetches and re-serves same-origin via KeenPhoenixSvelte.Apps.Proxy — no CORS, CSP 'self').
• Example reworked into "KeenSpace" — the demo is now a Teams-style workspace that doubles as reference code: chat over channel + Presence, a video catalogue over the REST helper, a calendar over context.tokens, a bus-driven activity toast, simulated i18n, a plain (non-LiveView) route, and Lit/React/vanilla islands alongside the Svelte ones.

What's New in v1.0.0-rc.1

• Islands for Phoenix — <.svelte> mounts compiled Svelte apps with zero per-page wiring — The initial release ships the core mounting path: a <.svelte name id props> function component renders a hook-bound <div> (phx-update="ignore", data-app, JSON data-props), and the KeenSvelte LiveView hook mounts the app on mounted(), pushes prop changes on updated(), and tears it down on destroyed(). AppsManager lazily import()s /apps/<name>/main.mjs and caches it, so only the bundles actually present on a page are fetched — no manual <script>/<link> tags per app.
• One component, two transports — LiveView socket or plain-page REST — Apps mount identically inside a LiveView or on a plain controller-rendered page. mountStatic() scans [data-app] on non-LiveView pages (skipping [data-phx-session]) and mounts with live: null, so the same app talks over live.pushEvent when a socket is present and falls back to the api REST helper when it isn't.
• A standardized app boundary — props, context, live, api, channel, bus — Every app's entry receives (target, { props, context, live, api, channel, bus, el }) => handle. context (emitted once per page by <KeenPhoenixSvelte.runtime>) carries user/csrf/tokens/api_base/socket; live bridges pushEvent/handleEvent (with automatic subscription cleanup)/upload; api attaches x-csrf-token + session cookie to REST calls; channel is a promise-based, envelope-agnostic Phoenix channel factory with auto cid correlation; and bus is a page-wide client-side event bus (emit/on/once) for island-to-island messaging that works identically with or without LiveView.
• Svelte-version-agnostic mount contract — The mount handle is { setProps, destroy }, so the hook drives Svelte 5 (mount/unmount + $state) and transparently falls back to $set/$destroy on Svelte 4. Prop updates are diffed in updated() to skip redundant re-renders when data-props is unchanged.
• Dual package — Hex library + bundled npm package — Ships as both keen_phoenix_svelte on Hex and @keenmate/phoenix_svelte on npm, released in lockstep at the same version. A Vite config helper (@keenmate/phoenix_svelte/vite) builds one self-contained ES module per app with CSS injected by JS. A runnable Phoenix 1.8 demo (the like app on both a LiveView route and a plain route, plus a channel) lives in example/.

How it works

Two cooperating halves:

• Elixir — <.svelte> renders a hook-bound <div> (phx-update="ignore", data-app, JSON data-props); <KeenPhoenixSvelte.runtime> emits the page context.
• JS — the KeenSvelte hook mounts the app inside a LiveView and AppsManager lazily import()s /apps/<name>/main.mjs; mountStatic() mounts apps on plain pages. Only the bundles on a page are fetched.

phx-update="ignore" keeps LiveView out of the Svelte-owned subtree; the hook drives mount / prop-update / teardown across live navigation.

Unlike live_svelte, this is the island model — no ~V sigil, no server-rendered slots, no SSR Node runtime.

Install

{:keen_phoenix_svelte, "~> 1.0"}

Plus the npm package @keenmate/phoenix_svelte and a Svelte/Vite toolchain. Full steps in Installation & setup.

Documentation

• Installation & setup — wire the library into your app
• Authoring apps — folder layout, the mount contract, Svelte 5 & 4
• Server communication — runtime context, live, api, channel, bus
• External apps (CDN, direct vs proxy) — load islands from elsewhere, and the :direct/:proxy delivery modes

A complete, runnable demo (the like app on a LiveView route and a plain route, plus a channel) lives in the example/ app.

Versioning

keen_phoenix_svelte is a dual package: the Hex library keen_phoenix_svelte and the npm package @keenmate/phoenix_svelte are released in lockstep at the same version — install matching versions of both. The Elixir side renders the component + hook wiring; the npm side supplies the client runtime (the KeenSvelte hook, AppsManager, the api/channel helpers, and the Vite build helper).

License

MIT.