LiveViewReact.SSR behaviour (liveview_react v1.0.0)

A behaviour for rendering React components server-side.

To define a custom renderer, change the application config in config.exs:

config :liveview_react, ssr_module: MyCustomSSRModule

Exposes a telemetry span for each render under key [:liveview_react, :ssr]

Summary

Types

event_command()

One Phoenix JavaScript command encoded for an SSR event callback.

events()

Event callback props mapped to ordered Phoenix JavaScript command lists.

json_value()

A JSON-compatible value used in a materialized stream item.

props()

The plain prop map passed to an SSR renderer.

render_response()

The normalized HTML returned by render/1.

request()

The exact transport-v2 request passed to a configured SSR renderer.

slots()

Rendered slot HTML keyed by default or a named slot.

stream_item()

A materialized stream item passed to an SSR renderer.

streams()

A dead-render stream snapshot keyed by non-empty stream name.

Callbacks

render(request)

Renders one validated transport-v2 request as a complete HTML binary.

Functions

render(request)

Validates and renders a transport-v2 request with the configured SSR module.

Types

event_command()

@type event_command() :: [String.t() | map(), ...]

One Phoenix JavaScript command encoded for an SSR event callback.

The command is exactly [operation, options], where operation is a lowercase command name and options is a plain map. Elixir typespecs cannot express a fixed-length heterogeneous list, so the element type below is intentionally broader than the runtime validation.

events()

@type events() :: %{optional(String.t()) => [event_command()]}

Event callback props mapped to ordered Phoenix JavaScript command lists.

Event names use React's onEvent naming convention.

json_value()

@type json_value() ::
  nil
  | boolean()
  | number()
  | String.t()
  | [json_value()]
  | %{optional(String.t()) => json_value()}

A JSON-compatible value used in a materialized stream item.

props()

@type props() :: %{optional(String.t() | atom() | integer()) => term()}

The plain prop map passed to an SSR renderer.

Keys must be non-empty, string-compatible names and cannot use prototype-sensitive JavaScript property names.

render_response()

@type render_response() :: %{html: binary()}

The normalized HTML returned by render/1.

request()

@type request() :: %{
  version: 2,
  component: String.t(),
  events: events(),
  identifierPrefix: String.t(),
  props: props(),
  streams: streams(),
  slots: slots()
}

The exact transport-v2 request passed to a configured SSR renderer.

All seven fields are required and additional fields are rejected.

slots()

@type slots() :: %{optional(String.t()) => String.t()}

Rendered slot HTML keyed by default or a named slot.

stream_item()

@type stream_item() :: %{required(String.t()) => json_value()}

A materialized stream item passed to an SSR renderer.

Every item is a plain JSON object with string keys and a unique, non-empty "__dom_id" string field.

streams()

@type streams() :: %{optional(String.t()) => [stream_item()]}

A dead-render stream snapshot keyed by non-empty stream name.

Callbacks

render(request)

@callback render(request()) :: binary()

Renders one validated transport-v2 request as a complete HTML binary.

Renderer implementations should raise LiveViewReact.SSR.NotConfigured when their infrastructure is unavailable and LiveViewReact.SSR.RenderError when rendering fails.

Functions

render(request)

@spec render(request()) :: render_response()

Validates and renders a transport-v2 request with the configured SSR module.

Returns the renderer's HTML in a normalized %{html: html} response. Raises LiveViewReact.SSR.NotConfigured when required SSR infrastructure is unavailable and LiveViewReact.SSR.RenderError when the request or renderer response is invalid, or when a built-in renderer fails. Other exceptions raised by a custom renderer propagate unchanged.