LiveReact

In LiveReact 2.0, instead of re-sending the entire props payload on every update, the library sends only the changes (patches). This is achieved using three data attributes on the component's wrapper element:

• data-props: A full snapshot of the props, written on the initial render to allow clients to resynchronize upon reconnection.
• data-props-diff: Patch operations describing what changed since the last render.
• data-streams-diff: Patch operations specifically for stream assigns.

The client hook uses a fourth attribute, data-use-diff, to determine whether to read from the full snapshot or the diff.

Diffs are computed using LiveView's change tracking. For lists of maps, LiveReact matches items on their id field, meaning reordering or inserting items does not require re-sending untouched entries. The operations are serialized in a compact format defined by LiveReact.Patch.

LiveReact uses two distinct mechanisms to minimize wire payload and optimize React re-renders:

1. Props Diffing: Instead of re-sending the full data-props JSON on every update, the server computes a JSON-Patch-style diff using the Jsonpatch library and sends it via data-props-diff. On the client, these patches are applied using a copy-on-write strategy. This ensures that unaffected items in an array or object keep their original references, allowing React.memo to successfully skip re-renders for unchanged data.

2. LiveView Streams: %Phoenix.LiveView.LiveStream{} assigns are automatically detected and routed to a streams map. Because streams do not hold a full snapshot server-side, they are communicated exclusively via data-streams-diff patches (handling reset?, deletes, and inserts). The client builds the stream state from scratch starting from an empty object {}.

Client-side State Merging: On every update, the React component re-renders with a merged object containing both props and streams: {...this._props, ...this._streams, pushEvent, ...}.

LiveReact supports Phoenix.LiveView.LiveStream by calculating specific patch operations for stream updates. This allows the React frontend to efficiently sync with LiveView streams (insertions, deletions, resets, or limits) without re-rendering the entire list.

Key patch operations for streams include:

• replace: Used for initial renders or resetting a stream (e.g., {%{op: "replace", path: "/users", value: []}%}).
• upsert: Used when inserting items into a stream (e.g., {%{op: "upsert", path: "/users/-", value: %{...}%}).
• remove: Used when deleting an item (e.g., {%{op: "remove", path: "/users/$$users-2"}%}).
• limit: Used when a stream limit is applied (e.g., {%{op: "limit", path: "/users", value: 5}%}).

Stream diffs are provided to the React component via the data-streams-diff attribute.

# Example of expected stream patch shapes:
# Insertion:
%{"op" => "upsert", "path" => "/users/-", "value" => %{"id" => 3, "name" => "Charlie", "age" => 28, "__dom_id" => "users-3"}}

# Deletion:
%{"op" => "remove", "path" => "/users/$$users-2"}

# Reset:
%{"op" => "replace", "path" => "/users", "value" => []}

LiveReact supports Phoenix.LiveView.stream/3,4 assigns. When you pass a value of type %Phoenix.LiveView.LiveStream{} as a prop to a <.react /> component, LiveReact automatically handles it as a stream, delivering updates over data-streams-diff instead of re-sending the entire list.

To use this, ensure your LiveView uses stream/3 or stream/4 to manage the data and pass the stream assign to the component.

# In your LiveView
def mount(_params, _session, socket) do
  socket = 
    socket
    |> assign(:next_id, 1)
    |> stream(:messages, [%{id: 0, text: "Welcome!"}])
  {:ok, socket}
end

# In your render/template
<.react name="StreamDemo" messages={@streams.messages} socket={@socket} />

// In your React component
export default function StreamDemo({ messages, pushEvent }) {
  return (
    <ul>
      {messages.map((message) => (
        <li key={message.__dom_id}>
          {message.text}
        </li>
      ))}
    </ul>
  );
}

LiveReact implements a compact wire format to send only changes (diffs) to the client instead of full JSON payloads. This is achieved through two main mechanisms:

1. Props Diffing: The server uses LiveReact.Encoder to normalize structs into maps and Jsonpatch.diff/3 to compute differences. These are serialized via LiveReact.Patch into data-props-diff attributes.
2. LiveView Streams: Data from Phoenix.LiveView.stream/3,4 is processed by hand-rolled patch generation that reads %Phoenix.LiveView.LiveStream{} operations directly, serialized into data-streams-diff attributes.

Client-side behavior: The React hook maintains persistent _props and _streams state per component instance. It applies patches using a copy-on-write strategy: only the top-level value at each patch's first path segment receives a new reference. This ensures that React.memo'd children correctly skip re-rendering for untouched items while re-rendering only when necessary.

The LiveReact.Patch module encodes patch operations into a compact binary format used for data-props-diff and data-streams-diff attributes. This format is optimized for transport via HTML attributes.

It uses a concatenated sequence of operations where dynamic text fields (paths and values) are prefixed with their JavaScript string length. This allows paths and values to contain delimiters without requiring complex escaping.

Operation Codes

Value Tags

For SSR deployments, nodejs must be installed in both the build stage and the final runtime stage. Modify your ./Dockerfile as follows:

1. Build Stage: Add curl to dependencies, install nodejs (19.x), and run npm install in /app/assets.
2. Runtime Stage: In the stage starting with FROM ${RUNNER_IMAGE}, add curl to the apt-get install list and install nodejs via the Nodesource setup script.

# ./Dockerfile

...

# install build dependencies
- RUN apt-get update -y && apt-get install -y build-essential git \
+ RUN apt-get update -y && apt-get install -y build-essential git curl \
    && apt-get clean && rm -f /var/lib/apt/lists/*_*

+ # install nodejs for build stage
+ RUN curl -fsSL https://deb.nodesource.com/setup_19.x | bash - && apt-get install -y nodejs

...

COPY assets assets

+ # install all npm packages in assets directory
+ RUN cd /app/assets && npm install

...

# start a new build stage so that the final image will only contain
# the compiled release and other runtime necessities
FROM ${RUNNER_IMAGE}

RUN apt-get update -y && \
-  apt-get install -y libstdc++6 openssl libncurses5 locales ca-certificates \
+  apt-get install -y libstdc++6 openssl libncurses5 locales ca-certificates curl \
   && apt-get clean && rm -f /var/lib/apt/lists/*_*

+ # install nodejs for production environment
+ RUN curl -fsSL https://deb.nodesource.com/setup_19.x | bash - && apt-get install -y nodejs

...