Stateless SSE helpers for Datastar in any Plug/Phoenix app.

Datastar provides a set of composable, stateless functions that write Server-Sent Events (SSE) to a chunked Plug.Conn response. The Datastar JavaScript client library running in the browser receives these events and applies DOM patches, signal updates, script executions, and redirects — all without a full-page reload.

Installation

Add datastar_plug to your mix.exs dependencies:

def deps do
  [
    {:datastar_plug, "~> 0.2.0"}
  ]
end

Quick Start

Phoenix controller

defmodule MyAppWeb.ItemController do
  use MyAppWeb, :controller
  alias Datastar
  alias MyApp.Items

  # GET /items/:id/edit — triggered by a Datastar `data-init` attribute
  def edit(conn, %{"id" => id} = params) do
    signals = Datastar.parse_signals(params)
    item = Items.get!(id)
    form_html = render_to_string(conn, :edit_form, item: item)

    conn
    |> Datastar.init_sse()
    |> Datastar.patch_fragment(form_html, selector: "#item-form")
    |> Datastar.patch_signals(%{editMode: true, itemId: id})
    |> Datastar.close_sse()
  end

  # PUT /items/:id — save changes and update the display
  def update(conn, %{"id" => id} = params) do
    signals = Datastar.parse_signals(params)
    item_attrs = Map.take(signals, ["title", "description"])
    {:ok, item} = Items.update(id, item_attrs)
    display_html = render_to_string(conn, :display, item: item)

    conn
    |> Datastar.init_sse()
    |> Datastar.patch_fragment(display_html, selector: "#item-display")
    |> Datastar.patch_signals(%{editMode: false})
    |> Datastar.close_sse()
  end
end

Plain Plug.Router

defmodule MyApp.Router do
  use Plug.Router

  plug :match
  plug Plug.Parsers, parsers: [:json], json_decoder: Jason
  plug :dispatch

  get "/updates" do
    conn
    |> Datastar.init_sse()
    |> Datastar.patch_fragment(~s(<div id="status">OK</div>))
    |> Datastar.close_sse()
  end
end

Long-running SSE streams with connection checking

def stream(conn, _params) do
  conn = Datastar.init_sse(conn)
  do_stream(conn, items())
end

defp do_stream(conn, []), do: conn

defp do_stream(conn, [item | rest]) do
  case Datastar.check_connection(conn) do
    {:ok, conn} ->
      conn
      |> Datastar.patch_fragment(render_item(item))
      |> do_stream(rest)

    {:error, _conn} ->
      # Client disconnected — stop streaming silently
      conn
  end
end

SSE Event Protocol

Each SSE event emitted by this library follows the format required by the Datastar SSE specification:

event: <event-type>\n
[id: <event-id>\n]
[retry: <ms>\n]
data: <key> <value>\n
...more data lines...\n
\n

The blank line (double newline \n\n) terminates the event. Multi-line values (e.g. multi-line HTML) are split into multiple data: lines, one per original line.

Security Considerations

See the Datastar security reference for the full specification. Key points for this library:

• patch_fragment/3 — HTML is written verbatim to the SSE stream. If any part of the HTML originates from user input, the caller must sanitise it before passing it to this function to prevent XSS.

• patch_signals/3 — Signal values are JSON-encoded via Jason, so they are safe against injection in the SSE stream itself. However, if signal values are later rendered into HTML on the server, standard output-encoding rules apply.

• execute_script/3 — Executes arbitrary JavaScript on the client. Only pass server-controlled strings. Never interpolate user input directly into the script string.

• redirect_to/3 — The URL is JSON-encoded via Jason before being embedded in the window.location.href assignment, preventing injection via single-quotes, backslashes, or </script> in the URL.

• parse_signals/1 — Signal data arrives from the browser (user- controlled). Treat all parsed values as untrusted input. Validate and sanitise before using them in queries, rendering, or downstream logic.