Overview

StarView is an Elixir SDK for Datastar Server-Sent Events. It works with Plug and Phoenix, and uses Erlang's built-in :json module.

The Problem

Building Datastar apps in Elixir can mean a lot of repeated wiring. You start SSE responses, track which values need to reach the browser, render updated HTML, and keep event handlers mapped to the modules that own them.

StarView keeps that flow close to normal Phoenix controller code.

What StarView Adds

signal/3 sets a connection assign and exposes the same value as a Datastar signal. Function components can read the assign, while the browser receives the signal during the initial render or immediately during an SSE event.

def handle_event("increment", %{"count" => count}, %{method: "POST"} = conn)
    when is_integer(count) and count >= 0 and count < 1_000_000 do
  conn
  |> Plug.Conn.assign(:label, "Count")
  |> signal(:count, count + 1)
  |> patch_element(&summary/1)
end

The submitted count is UI state in this example, not an authorized persisted record. The complete counter guide includes its component, initial render, and invalid-input path.

Dispatch Flow

The Phoenix dispatcher starts the SSE response before your handler runs. Your controller handles the event and returns the updated connection:

@impl StarView
def handle_event("refresh", _signals, conn) do
  signal(conn, :refresh_complete, true)
end

Any controller that uses use StarView is automatically dispatchable through StarView.Dispatch, so you do not maintain an allow-list for Phoenix controllers.

Next Steps

Start with the installation guide, then add the Phoenix web module section and routes. Once the app is running, the core guides cover patch_signals/3, patch_element/3, and optional per-tab stream deduplication.

Choose the rendering and state boundary

Default to server-rendered HEEx with ordinary Datastar signals for form values, visibility, and small reactive controls. A widget that owns timers, drag state, external browser integrations, or repeated independent instances may benefit from Rocket, Datastar's beta custom-element API with scoped client state and lifecycle hooks.

This is an application design choice: use props for the widget's public inputs and local state for its internal interaction. Keep business writes and policies on the server. Check the exact Rocket client you bundle before adopting its beta API; StarView's release does not establish a Rocket version or supply its assets.

The optional StarView.Page, StarView.Component and StarView.Router APIs are available alongside existing controllers. Use the integration that fits the application's rendering boundary; adopting Datastar does not require rewriting its backend or controller pages.

Read Thinking in Phoenix, Datastar and StarView for the request, state and backend model, including the ideas we took from Jacob O'Bryant's Biff implementation.

For concrete workflows, read the manual Plug endpoint, PubSub stream, safe action, and troubleshooting guides.