From 542326cf92ab4e3e01266d49952e037fe1bb2d14 Mon Sep 17 00:00:00 2001 From: Denis Donici Date: Fri, 6 Mar 2026 00:54:25 +0200 Subject: [PATCH] chore: update docs --- README.md | 23 +++++++++-------------- example_project/README.md | 20 ++++++++------------ guides/api_reference.md | 4 ++-- guides/configuration.md | 15 +++++++++------ guides/installation.md | 15 ++++++++++++++- guides/introduction.md | 2 +- guides/ssr.md | 10 ++-------- guides/troubleshooting.md | 17 +++++++++++------ 8 files changed, 56 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 117bda1..f9fe2af 100644 --- a/README.md +++ b/README.md @@ -87,7 +87,7 @@ If you don't want SSR, you can disable it by not setting `NodeJS.Supervisor` in _If you're updating from an older version, make sure to check the `CHANGELOG.md` for breaking changes._ -LiveSvelte uses [Vite](https://vite.dev/) as its build tool with `@sveltejs/vite-plugin-svelte` for Svelte compilation. The recommended way to install is via the [Igniter](https://github.com/ash-project/igniter) installer, which automates all configuration steps. +LiveSvelte uses [Vite](https://vite.dev/) for building and [phoenix_vite](https://github.com/LostKobrakai/phoenix_vite) to integrate it with Phoenix. The layout uses `PhoenixVite.Components.assets`; in development the endpoint runs a Vite watcher and points asset URLs at the Vite dev server so Svelte and CSS changes hot-reload with no extra terminal. The recommended way to install is via the [Igniter](https://github.com/ash-project/igniter) installer, which configures phoenix_vite (including the dev watcher and `static_url`) and all LiveSvelte steps. ### Option A — Igniter installer (recommended) @@ -208,6 +208,8 @@ config :phoenix_vite, PhoenixVite.Npm, Use `PhoenixVite.Components.assets` in your root layout and `import PhoenixVite.Plug` + `plug :favicon, dev_server: {PhoenixVite.Components, :has_vite_watcher?, [__MODULE__]}` in the endpoint. Without phoenix_vite, use `LiveSvelte.Reload.vite_assets` in the layout and run Vite manually. +**For instant Svelte/CSS HMR**, add to your endpoint in `config/dev.exs`: `static_url: [host: "localhost", port: 5173]` and in `watchers` add `vite: {PhoenixVite.Npm, :run, [:vite, ~w(dev)]}`. The Igniter installer does this for you; if you add phoenix_vite or LiveSvelte manually, add these so the layout serves assets from the Vite dev server and HMR works. + **5.** Update `assets/vite.config.mjs` to add the Svelte and LiveSvelte plugins: ```js @@ -290,8 +292,8 @@ children = [ **13.** Install npm packages and build: ```bash -cd assets && npm install && cd .. -mix assets.js +mix assets.setup +mix assets.build mix phx.server ``` @@ -349,11 +351,10 @@ git clone https://github.com/woutdp/live_svelte.git # set up and run the example project cd live_svelte/example_project mix setup -mix assets.js mix phx.server ``` -Server will be running on `localhost:4000`. If you want to change the port, edit `example_project/config/dev.exs` and change the `http` config. +The example project uses phoenix_vite: `mix phx.server` starts both Phoenix and the Vite dev server, so Svelte/CSS changes hot-reload. Server will be running on `localhost:4000`. If you want to change the port, edit `example_project/config/dev.exs` and change the `http` config. If you have examples you want to add, feel free to create a PR, I'd be happy to add them. @@ -896,20 +897,14 @@ Inside `assets/package.json` LiveSvelte ships TypeScript source directly — there are no pre-built distribution files. Consumers compile the library source through their own Vite pipeline via the `live_svelte` package alias. -When working on the library source in `assets/js/live_svelte/`, changes are picked up automatically by the example project's Vite builds: +When working on the library source in `assets/js/live_svelte/`, rebuild the example project so Vite picks up the changes: ```bash # From example_project/ — rebuild after library source changes: -mix assets.js && mix compile +mix assets.build && mix compile ``` -For live development with HMR: -```bash -# Terminal 1: Phoenix server -cd example_project && mix phx.server -# Terminal 2: Vite dev server (HMR for Svelte + library changes) -cd example_project/assets && npx vite -``` +The example project uses phoenix_vite, so a single `mix phx.server` starts both Phoenix and the Vite dev server; Svelte and library changes hot-reload with no second terminal. **Type checking:** The LiveSvelte client library is written in TypeScript with a type-safe public API (no `any` in exported types). Consumers get type hints via the package `types` entry. From the library repo, run `npm run typecheck` in `live_svelte/assets` to run `tsc --noEmit`. diff --git a/example_project/README.md b/example_project/README.md index 94311f1..8786942 100644 --- a/example_project/README.md +++ b/example_project/README.md @@ -1,7 +1,7 @@ # LiveSvelte Example Project A working Phoenix application demonstrating LiveSvelte features — Svelte 5 components -integrated with Phoenix LiveView. +integrated with Phoenix LiveView. It uses [phoenix_vite](https://github.com/LostKobrakai/phoenix_vite) for Vite: one `mix phx.server` starts Phoenix and the Vite dev server, so Svelte and CSS changes hot-reload with no extra terminal. ## Setup @@ -65,7 +65,7 @@ mix test **After changing JS/Svelte files**, rebuild before running tests: ```bash -mix assets.js && mix test +mix assets.build && mix test ``` E2E tests require Chrome + ChromeDriver in PATH. Install with your OS package manager. @@ -73,21 +73,17 @@ See `live_svelte/CLAUDE.md` for detailed testing guidance. ## SSR (Server-Side Rendering) -SSR is disabled by default in development. To enable: +In development the app uses `LiveSvelte.SSR.ViteJS`: SSR requests go to the Vite dev server (started by the `:vite` watcher in `config/dev.exs`). The endpoint’s `static_url` and `watchers` are set so that assets and HMR are served from Vite. -**config/dev.exs:** +**config/dev.exs** (already set in this project): ```elixir -config :live_svelte, ssr: true, ssr_module: LiveSvelte.SSR.ViteJS +config :live_svelte, ssr_module: LiveSvelte.SSR.ViteJS, vite_host: "http://localhost:5173" +# Endpoint also has static_url: [host: "localhost", port: 5173] and watchers: [..., vite: {PhoenixVite.Npm, :run, [:vite, ~w(dev)]}] ``` -**For production**, use NodeJS SSR (already configured): -```elixir -config :live_svelte, ssr: true, ssr_module: LiveSvelte.SSR.NodeJS -``` - -Build the SSR bundle before SSR works: +**For production**, NodeJS SSR is used (already configured); build the SSR bundle with: ```bash -mix assets.js && mix compile +mix assets.build && mix compile ``` The SSR demo page (`/live-ssr`) uses `ssr={true}` on the component. NodeJS must be available for SSR in production; in test env SSR is disabled globally via `config :live_svelte, ssr: false`. diff --git a/guides/api_reference.md b/guides/api_reference.md index cd95704..1edb25e 100644 --- a/guides/api_reference.md +++ b/guides/api_reference.md @@ -131,9 +131,9 @@ Without `@derive`, passing a struct as a prop will raise an error. ### `LiveSvelte.Reload` / `vite_assets/1` -When using the Igniter installer with phoenix_vite, the layout uses `PhoenixVite.Components.assets` instead. Use `LiveSvelte.Reload.vite_assets/1` when not using phoenix_vite (e.g. manual setup). +**With phoenix_vite:** The layout uses `PhoenixVite.Components.assets`; ensure `config/dev.exs` has the endpoint’s `static_url: [host: "localhost", port: 5173]` and `watchers: [..., vite: {PhoenixVite.Npm, :run, [:vite, ~w(dev)]}]` so the Vite dev server runs and HMR works. The Igniter installer adds these. -HMR helper for development. Includes the Vite dev server client script. +**Without phoenix_vite:** Use `LiveSvelte.Reload.vite_assets/1` in your layout. HMR helper for development; includes the Vite dev server client script. ```heex diff --git a/guides/configuration.md b/guides/configuration.md index 3ea1a70..3306294 100644 --- a/guides/configuration.md +++ b/guides/configuration.md @@ -84,18 +84,21 @@ export default defineConfig({ svelte(), liveSveltePlugin({ // Options (all optional): - paths: ["assets/svelte"], // Directories to scan for .svelte files - entrypoint: "assets/js/app.js" // Main app entry point + components: ["./svelte/**/*.svelte"], // Glob(s) for component discovery (default) + entrypoint: "./js/server.js" // SSR entry for /ssr_render (default) }) ] }) ``` -### Default Paths +### Defaults -By default, `liveSveltePlugin` discovers Svelte components in: -- `assets/svelte/**/*.svelte` -- `lib/**/*.svelte` (for colocated components next to LiveView modules) +- **components** — `["./svelte/**/*.svelte"]`; patterns are relative to the Vite project root (where `vite.config.mjs` lives). +- **entrypoint** — `"./js/server.js"`; used by the plugin’s `/ssr_render` middleware in development and by the SSR build. + +### Instant HMR with phoenix_vite + +When using phoenix_vite, the layout uses `PhoenixVite.Components.assets`. For Svelte/CSS changes to hot-reload, your endpoint in `config/dev.exs` must have `static_url: [host: "localhost", port: 5173]` and a `:vite` watcher (e.g. `vite: {PhoenixVite.Npm, :run, [:vite, ~w(dev)]}`). The Igniter installer adds these; see [Installation](installation.md) or [Troubleshooting](troubleshooting.md) if you set up manually. ## JSON Library diff --git a/guides/installation.md b/guides/installation.md index accac39..9b81e42 100644 --- a/guides/installation.md +++ b/guides/installation.md @@ -81,13 +81,25 @@ const liveSocket = new LiveSocket("/live", Socket, { config :live_svelte, ssr: true ``` -**`config/dev.exs`** — development SSR via Vite dev server: +**`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`: + ```elixir +# From phoenix_vite.install (required for HMR): +config :my_app, MyAppWeb.Endpoint, + static_url: [host: "localhost", port: 5173], + watchers: [ + tailwind: {Tailwind, :install_and_run, [:default, ~w(--watch)]}, + 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: ```elixir config :live_svelte, @@ -129,6 +141,7 @@ If you must install manually (e.g. Phoenix < 1.8), the overall steps mirror the 5. Add `import LiveSvelte` to `html_helpers` 6. Add `NodeJS.Supervisor` to `application.ex` 7. Configure SSR in `config/` +8. **For instant Svelte/CSS HMR with phoenix_vite:** In `config/dev.exs`, add to your endpoint `static_url: [host: "localhost", port: 5173]` and in `watchers` add `vite: {PhoenixVite.Npm, :run, [:vite, ~w(dev)]}`. Without these, the layout serves built assets and changes to Svelte components will not hot-reload. ## Disabling SSR diff --git a/guides/introduction.md b/guides/introduction.md index 974278c..1bcbd40 100644 --- a/guides/introduction.md +++ b/guides/introduction.md @@ -25,7 +25,7 @@ handle_event/3 pushEvent/handleEvent $props(), $state() - **Composables** — `useLiveSvelte`, `useLiveEvent`, `useLiveConnection`, `useLiveNavigation`, `useLiveForm`, `useLiveUpload`, `useEventReply` - **TypeScript** — Full type support across Elixir and JavaScript boundaries - **Igniter installer** — One-command setup with `mix igniter.install live_svelte` -- **Vite** — Development HMR and optimized production builds +- **phoenix_vite + Vite** — [phoenix_vite](https://github.com/LostKobrakai/phoenix_vite) integrates Vite with Phoenix: one `mix phx.server` starts both the app and the Vite dev server (when the installer’s `config/dev.exs` is used), giving instant Svelte/CSS HMR and optimized production builds ## When to Use LiveSvelte diff --git a/guides/ssr.md b/guides/ssr.md index 51af534..6800810 100644 --- a/guides/ssr.md +++ b/guides/ssr.md @@ -79,15 +79,9 @@ Components with `ssr={false}` render a loading slot or nothing on the first pain When running with `LiveSvelte.SSR.ViteJS`, changes to Svelte files trigger automatic hot module replacement. The `SvelteHook` re-mounts affected components without a full page reload. -When using phoenix_vite, the layout uses `PhoenixVite.Components.assets` and the Vite dev server is integrated automatically. When not using phoenix_vite, add the `LiveSvelte.Reload` module to your layouts to enable this: +**With phoenix_vite (recommended):** The layout uses `PhoenixVite.Components.assets`. The Igniter installer adds to your endpoint in `config/dev.exs` a `:vite` watcher and `static_url: [host: "localhost", port: 5173]`, so `mix phx.server` starts the Vite dev server and asset URLs point at it — Svelte and CSS then hot-reload with no extra terminal. See [Installation](installation.md) for the exact config; if you added phoenix_vite or LiveSvelte manually, add that endpoint config yourself. -```elixir -# config/dev.exs — added by the Igniter installer -config :live_svelte, - vite_host: "http://localhost:5173" -``` - -When not using phoenix_vite, use `LiveSvelte.Reload.vite_assets/1` in your layout to include Vite's HMR client and production fallback: +**Without phoenix_vite:** Use `LiveSvelte.Reload.vite_assets/1` in your layout to include Vite's HMR client and production fallback: ```heex diff --git a/guides/troubleshooting.md b/guides/troubleshooting.md index 9b16ff3..2852251 100644 --- a/guides/troubleshooting.md +++ b/guides/troubleshooting.md @@ -197,19 +197,24 @@ For containers that wrap multiple components, use `phx-update="ignore"` on the o **Cause:** `vite_host` is not reachable or Vite dev server isn't running. -**Fix:** Ensure `mix phx.server` starts the Vite watcher. Check `config/dev.exs`: +**Fix:** Ensure `mix phx.server` starts the Vite watcher and that asset URLs point at the Vite dev server. In `config/dev.exs` your endpoint must have: + +1. **`static_url: [host: "localhost", port: 5173]`** — so script/link tags and the HMR client load from Vite (port 5173). +2. **A `:vite` watcher** — so the Vite dev server is started with `mix phx.server` and `PhoenixVite.Components.has_vite_watcher?/1` returns true. + +Example (phoenix_vite with npm): ```elixir config :live_svelte, ssr_module: LiveSvelte.SSR.ViteJS, vite_host: "http://localhost:5173" -``` -And verify your `config/dev.exs` Phoenix watcher runs `vite`: - -```elixir config :my_app, MyAppWeb.Endpoint, + static_url: [host: "localhost", port: 5173], watchers: [ - node: ["node_modules/.bin/vite", cd: Path.expand("../assets", __DIR__)] + tailwind: {Tailwind, :install_and_run, [:default, ~w(--watch)]}, + vite: {PhoenixVite.Npm, :run, [:vite, ~w(dev)]} ] ``` + +Without these, the layout serves built assets from `priv/static` and Svelte/CSS changes do not hot-reload.