Welcome

LocalLiveView brings local-first interactivity to Phoenix applications by running your Elixir code directly in the browser — using the same Phoenix LiveView API you already know.

What is LocalLiveView?

In a standard Phoenix LiveView app, UI state lives on the server. Every interaction travels over the network: user clicks button → server processes event → server sends diff → browser updates DOM. This works great, but it means latency is always in the loop.

LocalLiveView moves that state into the browser itself. Your Elixir modules are compiled to WebAssembly and executed via Popcorn, which runs AtomVM — a tiny Erlang virtual machine — directly in the browser. Events are handled locally, renders happen instantly, and the server is only involved when you explicitly want it to be.

The result: zero-latency UI, offline capability, and a familiar Elixir/LiveView programming model.

How it works

           Server                                      Browser                 
┌───────────────────────────────┐              ┌──────────────────────────────┐
│ Phoenix LiveView (host)       │              │ Popcorn (AtomVM WASM)        │
│                               │              │                              │
│ render/1                      │              │ MyLocal                      │
│   <.local_live_view           │              │   mount/3                    │
│     view="MyLocal"            │─── assigns ─▶│   render/1                   │
│     items={@items} />         │              │   update/2                   │
│                               │              │                              │
│                               │              │   handle_event/3             │
│ handle_event/3                │◀─── event ───│     push_server_event/3      │
│                               │              │                              │
│ Mirror.MyLocal.handle_sync/3  │◀─── sync ────│   mirror_sync/2              │
│   (optional)                  │              │                              │
└───────────────────────────────┘              └──────────────────────────────┘

1. Your local/ project is compiled to a .avm WASM bundle at build time.
2. A server-side LiveView renders the mount point with <.local_live_view view="MyLocal" />. Every attribute other than view is passed down as assigns and delivered to the local view's update/2 callback — so the host stays in control of the data, exactly as with live_component/1.
3. When the page loads, Popcorn starts the WASM runtime and mounts your LocalLiveViews.
4. User interactions are handled in the browser — no round-trip to the server.
5. A local view can push events back to its host with push_server_event/3, which arrives at the host LiveView's handle_event/3. Handling the event locally first and pushing afterwards gives you optimistic updates, with the server's authoritative state arriving as the next update/2.
6. Optionally, you can sync selected assigns to a server-side mirror module via mirror_sync/2, letting other users' LiveViews react to local state changes.

Key concepts

LocalLiveView module — An Elixir module that uses use LocalLiveView and implements mount/3, render/1, and optionally handle_event/3. Lives in the local/ project (compiled to WASM).

local/ project — A separate Mix project inside your Phoenix app, built via mix llv.build. The local/ project depends on :local_live_view and contains all your client-side Elixir code.

<.local_live_view> — A Phoenix component that renders the mount point for a LocalLiveView. Generated by mix llv.install and available as import LocalLiveView.Component in your web module.

Mirror — An optional server-side module (Mirror.MyLocal) that receives synced assigns from a LocalLiveView. Useful for broadcasting state changes to other users or persisting data.

Relationship to Phoenix LiveView

If you know Phoenix LiveView, you already know LocalLiveView. The callbacks (mount/3, render/1 with ~H, handle_event/3), the assign functions (assign/2, update/3) and the template bindings (phx-click and friends) are all the same — LocalLiveView intercepts Phoenix LiveView's standard JavaScript layer, so event attributes work exactly the same way.

The main differences between LLV and standard LiveView are that LLV uses use LocalLiveView instead of use Phoenix.LiveView, relies on the update/3 callback to update its assigns, and runs directly in the browser's Popcorn runtime rather than on the server.

LLV can also render LiveComponents and function components natively. These will similarly execute as part of the browser's Popcorn runtime.