Phoenix.ReactServer.Helper (Phoenix.ReactServer NG v0.8.4)

Copy Markdown View Source

Phoenix.Component helpers for seamless React component integration.

This module provides react_component/1 helper function that enables rendering React components directly within Phoenix templates with automatic error handling, caching, and multiple rendering modes.

Features

  • Template Integration: Use React components in Phoenix.Component templates
  • Multiple Rendering Modes: Static markup, string rendering, and streaming
  • Error Handling: Graceful fallbacks for component rendering failures
  • Caching Support: Leverages Phoenix.ReactServer.Cache for performance
  • Type Safety: Full @spec specifications for compile-time checking

Usage

Import in your html_helpers function in lib/your_app_web.ex:

defp html_helpers do
  quote do
    # HTML escaping functionality
    import Phoenix.HTML

    # Core UI components
    import YourAppWeb.CoreComponents

    # React components
    import Phoenix.ReactServer.Helper
  end
end

Then create React component wrappers:

defmodule YourAppWeb.ReactComponents do
  use Phoenix.Component

  def react_chart(assigns) do
    react_component(%{
      component: "chart",
      props: assigns,
      static: Map.get(assigns, :static, false)
    })
  end
end

Rendering Modes

  • Static Markup (static: true): SEO-friendly, no hydration needed
  • String Rendering (static: false): Includes React data for hydration
  • Streaming: Automatic for large components via LiveView integration

Error Handling

When component rendering fails, the helper provides:

  • Development mode: Detailed error messages with stack traces
  • Production mode: Generic error messages for security
  • Graceful degradation: UI remains functional

Summary

Functions

react_component(assigns)

Renders a React component within a Phoenix template.

Functions

react_component(assigns)

@spec react_component(map()) :: Phoenix.LiveView.Rendered.t()

Renders a React component within a Phoenix template.

This helper provides a seamless way to integrate React components into your Phoenix templates with automatic error handling and caching support.

Attributes

  • component (required) - React component name (file without extension)
  • props (optional) - JSON-serializable map of component props (default: %{})
  • static (optional) - Rendering mode:
    • true - Static markup (no hydration)
    • false - String rendering with hydration support
    • nil - Readable stream rendering (default)

Examples

Basic Usage

<.react_component 
  component="chart" 
  props={%{data: @chart_data}} 
/>

Static Rendering for SEO

<.react_component 
  component="markdown" 
  props={%{content: @post.content}}
  static={true}
/>

Interactive Component with Hydration

<.react_component 
  component="dashboard" 
  props={%{user: @current_user}}
  static={false}
/>

Component File Structure

Component files should be located in the configured component_base directory and export a Component function:

// assets/component/chart.jsx
import Chart from 'awesome-chart';

export const Component = ({data, options = {}}) => {
  return <Chart data={data} {...options} />;
};

Error Handling

If rendering fails, the helper will log the error and render an error message in place of the component. In development, detailed error information is shown for debugging.

Attributes

  • component (:string) (required) - React component name (file without extension).

  • props (:map) - JSON-serializable map of component props. Defaults to %{}.

  • static (:atom) - Rendering mode:

    • true - Static markup (no hydration)
    • false - String rendering with hydration
    • nil - Readable stream rendering

    Defaults to nil. Must be one of true, false, or nil.