Installation

LiveSvelte uses Vite for both client and SSR builds, replacing the default esbuild setup in Phoenix projects.

Prerequisites

• Node.js 19+ or Bun — for package management and Vite builds. Production SSR (when using LiveSvelte.SSR.NodeJS) still requires Node.js 19+ on the server.
• Elixir 1.17+
• Phoenix 1.8+ — required for the Igniter installer
• Igniter — the installation scaffolding tool

Quick Start (Recommended)

Step 1: Install the Igniter archive

mix archive.install hex igniter_new

Step 2: Add LiveSvelte to your project

For an existing Phoenix 1.8+ project:

mix igniter.install live_svelte

For a new project with LiveSvelte pre-installed:

mix igniter.new my_app --with phx.new --install live_svelte

Using Bun

To use Bun instead of Node.js/npm for package management and Vite:

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

After install, mix assets.setup and mix assets.build use Bun (e.g. bun install, phoenix_vite's Bun task) instead of npm.

Step 3: Install JS dependencies and build

mix assets.setup    # phoenix_vite.npm assets install (or: mix setup)
mix assets.build
mix phx.server

Visit /svelte_demo to verify the installation with the generated demo component.

What the Installer Does

Running mix igniter.install live_svelte makes the following changes to your project:

package.json (at project root) — the installer moves it from assets/ and adds:

• live_svelte, phoenix_vite: "file:./deps/phoenix_vite" (dev), and Svelte-related deps

config/config.exs — adds config :phoenix_vite, PhoenixVite.Npm, ... (when using --bun, the installer configures PhoenixVite.Bun and Bun-based aliases instead).

assets/vite.config.mjs — adds the Svelte plugin, liveSveltePlugin, and ssr: { noExternal: ... }. A single config is used for both client and SSR builds (no separate vite.ssr.config.js); the SSR build is run via phoenix_vite.npm vite build --ssr js/server.js --outDir ../priv/svelte.

assets/js/app.js — adds hook wiring:

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

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

lib/app_web.ex — adds import LiveSvelte to html_helpers

lib/app/application.ex — adds a conditional NodeJS supervisor that only starts in production (where ssr_module is LiveSvelte.SSR.NodeJS):

node_js_children =
  if Application.get_env(:live_svelte, :ssr_module, nil) == LiveSvelte.SSR.NodeJS do
    [{NodeJS.Supervisor, [path: LiveSvelte.SSR.NodeJS.server_path(), pool_size: 4]}]
  else
    []
  end

children = node_js_children ++ [...]

config/config.exs — base SSR config:

config :live_svelte, ssr: true

config/dev.exs — the installer composes phoenix_vite.install first, which adds to your endpoint the Vite dev server watcher and static_url so that assets and HMR are served from Vite (port 5173). LiveSvelte then adds the live_svelte app config. Together this gives you instant Svelte/CSS HMR when you run mix phx.server:

# From phoenix_vite.install (required for HMR):
config :my_app, MyAppWeb.Endpoint,
  static_url: [host: "localhost", port: 5173],
  watchers: [
    vite: {PhoenixVite.Npm, :run, [:vite, ~w(dev)]}
  ]

# From live_svelte.install (development SSR):
config :live_svelte,
  ssr_module: LiveSvelte.SSR.ViteJS,
  vite_host: "http://localhost:5173"

If you add LiveSvelte or phoenix_vite manually (e.g. without running the Igniter installer), you must add the endpoint’s static_url and :vite watcher to config/dev.exs yourself; otherwise the layout will serve built assets and Svelte changes will not hot-reload.

config/prod.exs — production SSR via NodeJS:

config :live_svelte,
  ssr_module: LiveSvelte.SSR.NodeJS,
  ssr: true

mix.exs — adds phoenix_vite-driven aliases: assets.setup, assets.build (client + SSR via phoenix_vite.npm vite build):

"assets.setup": ["phoenix_vite.npm assets install"],
"assets.build": [
  "phoenix_vite.npm vite build --manifest --emptyOutDir true",
  "phoenix_vite.npm vite build --ssrManifest --emptyOutDir false --ssr js/server.js --outDir ../priv/svelte"
]

assets/svelte/ — creates the Svelte components directory with a demo component

assets/css/app.css — adds @source "../svelte/**/*.svelte"; if Tailwind is present (a bare directory path does not include .svelte files by default)

.gitignore — adds /assets/svelte/_build/ and /priv/svelte/

Manual Installation

If you must install manually (e.g. Phoenix < 1.8), follow the Option B — Manual installation steps in the README. Those steps are the authoritative reference and kept up to date.

Using Bun with manual installation

To use Bun instead of npm when installing manually:

1. Add the optional dependency in mix.exs: {:bun, ">= 1.5.1 and < 2.0.0-0"}
2. In config/config.exs, use config :phoenix_vite, PhoenixVite.Bun, ... (with the same options you would use for PhoenixVite.Npm; see phoenix_vite for the Bun API).
3. In mix.exs aliases, use phoenix_vite.bun instead of phoenix_vite.npm:
   • "assets.setup": ["phoenix_vite.bun assets install"]
   • "assets.build": same two phoenix_vite.bun vite build ... commands as in the npm version.
4. In config/dev.exs watchers, use vite: {PhoenixVite.Bun, :run, [:vite, ~w(dev)]}.

Production SSR still uses Node.js (LiveSvelte.SSR.NodeJS); the server must have Node.js 19+ installed.

Disabling SSR

If you don't need server-side rendering, disable it globally:

# config/config.exs
config :live_svelte, ssr: false

Or per-component:

<.svelte name="Counter" props={%{count: @count}} socket={@socket} ssr={false} />

Next Steps

• Basic Usage — your first <.svelte> component
• Configuration — all config options