Phoenix.ReactServer provides high-performance server-side rendering (SSR) for React components within Phoenix applications. It supports both Bun and Deno JavaScript runtimes with intelligent caching and hot reloading capabilities.

Features

• [x] Server-side rendering with multiple output formats:
  • Static markup generation (SEO-friendly)
  • String rendering with client hydration
  • Readable stream rendering (LiveView integration)
• [x] Dual runtime support (Bun and Deno)
• [x] Intelligent caching with TTL management
• [x] Hot reloading in development mode
• [x] LiveView integration with streaming support
• [x] Client-side hydration capabilities
• [x] Bundle size optimization (67% smaller than previous versions)

See the docs for more information.

Install this package

Add deps in mix.exs

{:phoenix_react_ng, "~> 0.5"},

Installation

Add to your dependencies in mix.exs:

{:phoenix_react_ng, "~> 0.5"},

Configuration

Configure the runtime, component paths, and caching options:

import Config

config :phoenix_react_ng, Phoenix.ReactServer,
  # Runtime: Bun (default) or Deno
  runtime: Runtime.Bun,
  # React component base path
  component_base: Path.expand("../assets/component", __DIR__),
  # Cache TTL in seconds (default: 60, set to 0 to disable)
  cache_ttl: 60

Supported Runtimes

• Bun Runtime (Runtime.Bun): Fast startup, excellent performance
• Deno Runtime (Runtime.Deno): Secure runtime with npm package support

Supervisor Configuration

Add to your application's supervisor tree:

def start(_type, _args) do
  children = [
    ReactDemoWeb.Telemetry,
    {DNSCluster, query: Application.get_env(:react_demo, :dns_cluster_query) || :ignore},
    {Phoenix.PubSub, name: ReactDemo.PubSub},
    # React render service
    Phoenix.ReactServer,
    ReactDemoWeb.Endpoint
  ]

  opts = [strategy: :one_for_one, name: ReactDemo.Supervisor]
  Supervisor.start_link(children, opts)
end

Usage Examples

Phoenix Component

Create Phoenix components that render React components:

defmodule ReactDemoWeb.ReactComponents do
  use Phoenix.Component
  import Phoenix.ReactServer.Helper

  def react_markdown(assigns) do
    {static, props} = Map.pop(assigns, :static, true)

    react_component(%{
      component: "markdown",
      props: props,
      static: static
    })
  end
end

Import your React components in lib/your_app_web.ex:

defp html_helpers do
  quote do
    # Translation
    use Gettext, backend: ReactDemoWeb.Gettext
    # HTML escaping functionality
    import Phoenix.HTML
    # Core UI components
    import ReactDemoWeb.CoreComponents
    import ReactDemoWeb.ReactComponents
  end
end

Rendering Methods

Static Markup (SEO-friendly)

Use static: true for SEO-friendly content that doesn't need client-side interaction:

<div class="card">
  <div class="card-body">
    <div class="card-title">Hello There</div>
    <.react_markdown data={@data} static={true} />
  </div>
</div>

String Rendering with Hydration

Use static: false (default) for components that need client-side interaction:

<div class="card w-full">
  <div class="card-body">
    <h3 class="card-title">
      This <code class="text-primary">Component</code> is rendered with server-side rendering
    </h3>
    <!-- Note: No whitespace between container and component for proper hydration -->
    <div class="w-full h-full" id="interactive-container"><.react_interactive_component data={@data} /></div>
  </div>
</div>

Then hydrate on the client:

import { hydrateRoot } from 'react-dom/client';

document.addEventListener('DOMContentLoaded', function() {
  const store = new Store();
  const domContainer = document.querySelector('#interactive-container');

  if (domContainer) {
    let channel = socket.channel("system_usage:lobby", {});

    channel.join()
      .receive("ok", resp => { console.log("Joined successfully", resp) })
      .receive("error", resp => { console.log("Unable to join", resp) });

    function Usage(props) {
      const data = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
      return <SystemUsage data={data} />;
    }

    channel.on("joined", (data) => {
      store.reset(data.data);
      requestAnimationFrame(() => {
        hydrateRoot(domContainer, <Usage />);
      });
    });

    channel.on("stats", (data) => {
      store.unshift(data);
    });
  }
});

Streaming with LiveView

Use streaming rendering for dynamic LiveView components:

<div
  id="react-live-form"
  class="w-full h-full"
  phx-update="ignore"
  phx-hook="LiveFormHook"
><.react_live_form data={@form_data} /></div>

Create LiveView hooks for streaming components:

const hooks = {
  LiveFormHook: {
    mounted() {
      const formState = new FormState();

      formState.setData = (data) => {
        this.pushEvent("form:input", data);
      };

      function LiveViewForm(props) {
        const data = useSyncExternalStore(
          formState.subscribe,
          formState.getSnapshot,
          formState.getServerSnapshot
        );
        return <LiveForm data={data} setData={formState.setData} />;
      }

      this.pushEvent("form:init", {}, (data, ref) => {
        formState.reset(data);
        this.reactRoot = hydrateRoot(this.el, <LiveViewForm />);
      });

      this.handleEvent("form:update", (data) => {
        formState.assign(data);
      });
    },
  }
}

Production Deployment

Bundle components and server code for production releases.

Production Bundling

For Bun Runtime:

mix phx.react.bun.bundle --component-base=assets/component --output=priv/react/server.js

For Deno Runtime:

mix phx.react.deno.bundle --component-base=assets/component --output=priv/react/server.js

Production Configuration

Configure in runtime.exs:

Bun Runtime:

config :phoenix_react_ng, Runtime.Bun,
  cmd: System.find_executable("bun"),
  server_js: Path.expand("../priv/react/server.js", __DIR__),
  port: 12666,
  env: :prod

Deno Runtime:

config :phoenix_react_ng, Runtime.Deno,
  cmd: System.find_executable("deno"),
  server_js: Path.expand("../priv/react/server.js", __DIR__),
  port: 12667,
  env: :prod

Client-Side Hydration with CDN

Hydrate React components on the client side using CDN modules:

<script type="importmap">
  {
    "imports": {
      "react-dom": "https://esm.run/react-dom@19",
      "app": "https://my.web.site/app.js"
    }
  }
</script>
<script type="module">
  import { hydrateRoot } from 'react-dom/client';
  import { App } from 'app';

  hydrateRoot(
    document.getElementById('app-wrapper'),
    <App />
  );
</script>

React Component Structure

React components should be placed in your configured component_base directory and export a default Component function:

// assets/component/my_component.js
import React from 'react';

export function Component({ title, children }) {
  return (
    <div className="my-component">
      <h1>{title}</h1>
      {children}
    </div>
  );
}

Performance Considerations

• Bundle Size: Components are optimized with 67% size reduction
• Caching: Intelligent caching with configurable TTL
• Hot Reloading: Automatic in development mode
• Streaming: Support for LiveView integration with streaming