LiveSvelte

The example project demonstrates several key integration patterns between Svelte 5 and Phoenix LiveView:

Core Integration

• Struct Props: Passing Elixir structs as props (requires @derive Jason.Encoder on the struct).
• Sigil Usage: Using the ~V sigil for inline Svelte templates.
• Lodash: Integrating npm packages directly within Svelte components.

Real-Time & Data

• Streams: Using Phoenix stream() for efficient list updates.
• Diffing: Utilizing Props Diff (JSON Patch) and ID List Diff for minimal updates.
• PubSub: Real-time updates via pushEvent and PubSub.

Composables (Hooks)

• useLiveForm(): Integration with Ecto changeset validation.
• useLiveUpload(): Handling file uploads with progress and validation.
• useLiveNavigation(): Managing patch/navigate actions.
• useLiveSvelte(): Enabling pushEvent within component trees.
• useEventReply(): Implementing request-response patterns.

When rendering multiple instances of the same Svelte component (e.g., in a loop), LiveSvelte needs stable DOM IDs to reconcile elements correctly. Use the following priority order for identity:

1. Explicit id: Pass id="my-id" to the component.
2. Explicit key: Pass key={index} to the component. The ID becomes ComponentName-<key>.
3. Auto-detected identity: If props contains :id, :key, :index, or :idx (or string equivalents), LiveSvelte uses that value.
4. Counter fallback: Sequential IDs (Name, Name-1, etc.). Note: This is unreliable inside comprehensions; always use one of the first three methods for loops.

<%!-- Using index in props for auto-generated IDs --%
<%= for {item, index} <- Enum.with_index(@list) do %>
  <.svelte name="Card" props={%{index: index, color: @color}} />
<% end %>

<%!-- Using explicit key attribute --%
<%= for {item, index} <- Enum.with_index(@list) do %>
  <.svelte name="Chart" key={index} props={%{data: item.data}} />
<% end %>

LiveSvelte enables end-to-end reactivity between Phoenix LiveView and Svelte 5 by bridging the server and client through a three-layer architecture:

1. LiveView (Elixir): The server renders an HTML wrapper div containing JSON-encoded props in a data-props attribute. State is managed on the server.
2. SvelteHook (Phoenix hook): A JavaScript hook that mounts and updates Svelte components. It reads the data-props attribute on mount and applies patches when the server sends updates.
3. Svelte 5 component: The client-side component that receives props via $props() and re-renders reactively using Svelte 5 runes (like $state() or $derived()) whenever updates are received.

User interactions in Svelte components are pushed back to the LiveView process using pushEvent, while server state flows down as reactive props.

LiveView (Elixir)     →   SvelteHook (Phoenix hook)   →   Svelte 5 (component)
server assigns              reads data attrs               reactive props
handle_event/3              pushEvent/handleEvent          $props(), $state()

The recommended installation method uses the Igniter installer. This automates the configuration of phoenix_vite, Vite, app.js, HTML helpers, SSR, and the layout with PhoenixVite.Components.assets.

For a New Project

Requires Phoenix 1.8+ and Node.js 19+ (or Bun).

mix archive.install hex igniter_new
mix igniter.new my_app --with phx.new --install live_svelte
cd my_app
mix setup
mix phx.server

For an Existing Project

1. Add {:igniter, "~> 0.6"} to your mix.exs dependencies.
2. Run the installer:

mix deps.get
mix igniter.install live_svelte

3. Install npm packages and build assets:

mix assets.setup     # Installs npm assets via phoenix_vite
mix assets.build     # Builds Vite client + SSR

4. Start the server:

mix phx.server

Using Bun

To use Bun instead of npm/npx, append the --bun flag:

• Existing project: mix igniter.install live_svelte --bun
• New project: mix igniter.new my_app --with phx.new --install live_svelte --bun

For manual installations, you must configure the frontend build system to work with LiveSvelte and Phoenix.

1. Create package.json (Project Root)

Create this in your project root (not in assets/). If using Tailwind, include the @tailwindcss/vite and tailwindcss packages.

{
  "type": "module",
  "dependencies": {
    "live_svelte": "file:./deps/live_svelte",
    "phoenix": "file:./deps/phoenix",
    "phoenix_html": "file:./deps/phoenix_html",
    "phoenix_live_view": "file:./deps/phoenix_live_view",
    "topbar": "^3.0.0"
  },
  "devDependencies": {
    "@sveltejs/vite-plugin-svelte": "^7.0.0",
    "phoenix_vite": "file:./deps/phoenix_vite",
    "svelte": "^5.0.0",
    "vite": "^8.0.0",
    "@tailwindcss/vite": "^4.1.0",
    "tailwindcss": "^4.1.0"
  }
}

2. Create assets/vite.config.mjs

This configuration handles the Svelte plugin, the LiveSvelte Vite plugin, and Tailwind (if used).

import { defineConfig } from "vite"
import { svelte } from "@sveltejs/vite-plugin-svelte"
import liveSveltePlugin from "live_svelte/vitePlugin"
import tailwindcss from "@tailwindcss/vite"

export default defineConfig(({ isSsrBuild }) => ({
  server: {
    host: "127.0.0.1",
    port: 5173,
    strictPort: true,
    cors: { origin: "http://localhost:4000" },
  },
  optimizeDeps: {
    include: ["live_svelte", "phoenix", "phoenix_html", "phoenix_live_view"],
  },
  ssr: { noExternal: process.env.NODE_ENV === "production" ? true : undefined },
  build: {
    manifest: false,
    ssrManifest: false,
    rollupOptions: {
      input: ["js/app.js", "css/app.css"],
      output: isSsrBuild ? { entryFileNames: "[name].mjs" } : undefined,
    },
    outDir: "../priv/static",
    emptyOutDir: true,
  },
  resolve: {
    alias: {
      "phoenix-colocated": `${process.env.MIX_BUILD_PATH}/phoenix-colocated`,
    },
  },
  plugins: [
    tailwindcss(),
    svelte({ compilerOptions: { css: "injected" } }),
    liveSveltePlugin({ entrypoint: "./js/server.mjs" }),
  ],
}))

3. Create assets/js/server.mjs

This file is required for SSR:

import { getRender } from "live_svelte"
import Components from "virtual:live-svelte-components"
export const render = getRender(Components)

4. Update assets/js/app.js

Import the LiveSvelte hooks and merge them into your LiveSocket:

import {getHooks} from "live_svelte"
import Components from "virtual:live-svelte-components"

const liveSocket = new LiveSocket("/live", Socket, {
  hooks: {...colocatedHooks, ...getHooks(Components)},
})

5. Update Layout and CSS

• Layout: In lib/<app_name>_web/components/layouts/root.html.heex, use PhoenixVite.Components.assets to load your JS and CSS.
• CSS: If using Tailwind v4, ensure your assets/css/app.css includes the Svelte source glob:

@import "tailwindcss";
@source "../svelte/**/*.svelte";