[LocalLiveView] Documentation by FranekKubis · Pull Request #581 · software-mansion/popcorn

FranekKubis · 2026-04-20T13:51:54Z

cd local_live_view and mix docs to generate documentation - then open doc/index.html to read

… llv usage.

mat-hek

We also need to go through the modules: make sure that only the public ones are visible and that they're have up-to-date docs. Also, it seems that mix docs only generates docs for the server part. Not sure if it's in scope of this PR, but needs to be fixed before the release.

mat-hek · 2026-07-31T14:21:54Z

+
+- A Phoenix project generated with `mix phx.new`
+- `:local_live_view` added as a dependency
+- `pnpm` or `npm` for JS package management


IIRC pnpm works only from popcorn repo root, so a regular user needs npm

mat-hek · 2026-07-31T14:23:48Z

+Visit [localhost:4000](http://localhost:4000). The installer generated a sample `HelloLocal` view — add it to any template to confirm everything works:
+
+```heex
+<.local_live_view view="HelloLocal" />
+```


Don't we generate a separate page that renders HelloLocal? If so, we can just tell the user to visit that page

mat-hek · 2026-07-31T14:27:19Z

+
+This should look familiar if you've used Phoenix LiveView. The differences are:
+
+- `use LocalLiveView` instead of `use Phoenix.LiveView`


Suggested change

- `use LocalLiveView` instead of `use Phoenix.LiveView`

This should look familiar if you've used Phoenix LiveView. The only difference is `use LocalLiveView` instead of `use Phoenix.LiveView`.

mat-hek · 2026-07-31T14:47:01Z

+## Building and running
+
+After adding the module, rebuild the WASM bundle:
+
+```bash
+mix llv.build
+```
+
+Then start or reload the server:
+
+```bash
+mix phx.server
+```


This is rather unnecessary, since the watcher detects changes. Besides, we describe that in the previous chapter.

Suggested change

## Building and running

After adding the module, rebuild the WASM bundle:

```bash

mix llv.build

```

Then start or reload the server:

```bash

mix phx.server

```

mat-hek · 2026-07-31T14:50:16Z

+└── mix.exs                 # Compiles to WASM via popcorn.cook
+```
+
+Add your LocalLiveView modules to `local/lib/`. They will be compiled into the WASM bundle when you run `mix llv.build`.


Suggested change

Add your LocalLiveView modules to `local/lib/`. They will be compiled into the WASM bundle when you run `mix llv.build`.

Now you can add your LocalLiveView modules to `local/lib/`. When the server is running, the LLV watcher detects changes and automatically rebuilds the local code. To enforce rebuild, run `mix llv.build` and restart the server.

mat-hek · 2026-07-31T14:54:58Z

+<.local_live_view view="ThermostatLocal" />
+```
+
+When mounting the same view multiple times, use the `id` attribute to give each instance a unique identifier.


This would fit better in the LocalLiveView module. I'd move it there. In this guide, you can add short comments inside the CounterLocal code, describing what each callback does in this particular case.

mat-hek · 2026-07-31T15:07:03Z

+```
+Browser                                       Server
+┌──────────────────────────────────────┐      ┌──────────────────┐
+│  Phoenix LiveView page               │      │  Phoenix app     │
+│                                      │      │                  │
+│  <.local_live_view view="MyLocal">   │      │  Mirror.MyLocal  │
+│         │                            │      │  (optional)      │
+│         ▼                            │      │       ▲          │
+│  Popcorn (AtomVM WASM)               │─────▶│  mirror_sync     │
+│    MyLocal (your Elixir code)        │      │                  │
+│    ├── mount/3                       │      └──────────────────┘
+│    ├── render/1                      │
+│    └── handle_event/3                │
+└──────────────────────────────────────┘
+```


It would be nice to show on this picture that the server LV can render LLV, pass assigns to it and exchange events

mat-hek · 2026-07-31T15:07:40Z

    [
-      # {:popcorn, "~> 0.3.0-rc2", targets: :wasm},
-      {:popcorn, path: "../popcorn/elixir", targets: :wasm},
+      {:popcorn, "~> 0.3.0-rc2", targets: :wasm},


Suggested change

{:popcorn, "~> 0.3.0-rc2", targets: :wasm},

{:popcorn, "~> 0.3.2", targets: :wasm},

mat-hek · 2026-07-31T15:08:16Z

+The source code for all examples is in the `examples/` directory of this repository:
+
+- `local-lv-thermostat` — Basic state management and events
+- `local-lv-forms` — Form handling with validation and Mirror Sync
+- `local-lv-compare` — Side-by-side comparison of Phoenix LiveView vs LocalLiveView


let's add kanban and burrito

mat-hek · 2026-07-31T15:13:37Z

+| Phoenix LiveView | LocalLiveView |
+|---|---|
+| `use Phoenix.LiveView` | `use LocalLiveView` |
+| `mount/3` | `mount/3` |
+| `render/1` with `~H` | `render/1` with `~H` |
+| `handle_event/3` | `handle_event/3` |
+| `assign/2`, `update/3` | `assign/2`, `update/3` |
+| `phx-click` | `phx-click` |
+| Runs on server | Runs in browser (WASM) |


I'm not sure if presenting this as a table is the good approach, since both columns are almost the same, and to understand it, you need to carefully read through it.

FranekKubis requested a review from mat-hek April 21, 2026 06:37

FranekKubis force-pushed the fk/llv-documentation branch 2 times, most recently from d39dc51 to 0f6a098 Compare April 21, 2026 06:51

FranekKubis force-pushed the fk/llv-documentation branch from 0f6a098 to ad3a5c2 Compare July 30, 2026 09:19

mat-hek removed their request for review July 30, 2026 10:47

FranekKubis requested a review from mat-hek July 31, 2026 14:15

FranekKubis added 5 commits July 31, 2026 16:35

New documentation for LocalLiveView.

70cbd0f

Rebase

82fb8be

Moved to specific popcorn version for the sake of outside of monorepo…

01577a3

… llv usage.

stash

f60f52b

installation doc update

f4b7e46

FranekKubis force-pushed the fk/llv-documentation branch from a13cea8 to f4b7e46 Compare July 31, 2026 14:35

mat-hek requested changes Jul 31, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[LocalLiveView] Documentation - #581

[LocalLiveView] Documentation#581
FranekKubis wants to merge 5 commits into
mainfrom
fk/llv-documentation

FranekKubis commented Apr 20, 2026 •

edited

Loading

Uh oh!

mat-hek left a comment

Uh oh!

mat-hek Jul 31, 2026

Uh oh!

mat-hek Jul 31, 2026

Uh oh!

mat-hek Jul 31, 2026

Uh oh!

mat-hek Jul 31, 2026

Uh oh!

mat-hek Jul 31, 2026

Uh oh!

mat-hek Jul 31, 2026

Uh oh!

mat-hek Jul 31, 2026

Uh oh!

mat-hek Jul 31, 2026

Uh oh!

mat-hek Jul 31, 2026

Uh oh!

mat-hek Jul 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		This should look familiar if you've used Phoenix LiveView. The differences are:

		- `use LocalLiveView` instead of `use Phoenix.LiveView`

	Add your LocalLiveView modules to `local/lib/`. They will be compiled into the WASM bundle when you run `mix llv.build`.
	Now you can add your LocalLiveView modules to `local/lib/`. When the server is running, the LLV watcher detects changes and automatically rebuilds the local code. To enforce rebuild, run `mix llv.build` and restart the server.

	{:popcorn, "~> 0.3.0-rc2", targets: :wasm},
	{:popcorn, "~> 0.3.2", targets: :wasm},

Uh oh!

Conversation

FranekKubis commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mat-hek left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

FranekKubis commented Apr 20, 2026 •

edited

Loading