Inertia.js Phoenix Adapter

The library automatically maps Phoenix flash data to the flash key within your Inertia props. When you use put_flash/3 in a Phoenix controller and redirect, the flash messages will be available in the frontend component's props under flash.

Example flow:

1. Controller calls conn |> put_flash(:info, "message") |> redirect(...).
2. Frontend receives props: { "props": { "flash": { "info": "message" } } }.

def update(conn, params) do
  case MyApp.Settings.update(params) do
    {:ok, _settings} ->
      conn
      |> put_flash(:info, "Settings updated")
      |> redirect(to: ~p"/settings")

    {:error, changeset} ->
      conn
      |> assign_errors(changeset)
      |> redirect(to: ~p"/settings")
  end
end

To avoid expensive computations during every request, especially when using partial reloads, you can pass a function reference to assign_prop/2.

• Standard Lazy Prop: Passing an anonymous function fn -> ... end or a named function reference ensures the computation is only performed when the prop is actually needed. It is included on the first visit.
• Optional Lazy Prop: Wrapping a function with Inertia.Controller.inertia_optional/1 ensures the prop is never included on the first visit; it will only be included if explicitly requested during a partial reload.

# ALWAYS included on first visit, but ONLY evaluated when needed
|> assign_prop(:expensive_thing, fn -> calculate_thing() end)

# NEVER included on first visit, ONLY evaluated when requested in a partial reload
|> assign_prop(:super_expensive_thing, inertia_optional(fn -> calculate_thing() end))

The easiest way to install the adapter is using Igniter. This automates the setup process and allows for customization via CLI flags.

Installation Commands

mix archive.install hex igniter_new
mix igniter.install inertia

Customization Options

Use these flags with the mix igniter.install inertia command:

• --client-framework [react|vue|svelte]: Configures the client-side framework in assets/package.json.
• --camelize-props: Sets camelize_props: true in config.exs.
• --history-encrypt: Sets history: [encrypt: true] in config.exs.
• --typescript: Creates a TypeScript config file and installs dev dependencies.

Update your config/config.exs to include an ssr build configuration for esbuild. This configuration should target node, use the cjs format, and output to the priv directory.

# config/config.exs

config :esbuild,
  version: "0.21.5",
  app: [
    args: ~w(js/app.jsx --bundle --target=es2020 --outdir=../priv/static/assets --external:/fonts/* --external:/images/*),
    cd: Path.expand("../assets", __DIR__),
    env: %{"NODE_PATH" => Path.expand("../deps", __DIR__)}
  ],
  ssr: [
    args: ~w(js/ssr.jsx --bundle --platform=node --outdir=../priv --format=cjs),
    cd: Path.expand("../assets", __DIR__),
    env: %{"NODE_PATH" => Path.expand("../deps", __DIR")}
  ]

To share data (like the authenticated user) on every single Inertia request, use assign_prop/2 within a Phoenix Plug in your response pipeline. This ensures the data is serialized and passed to all Inertia components.

defmodule MyApp.UserAuth do
  import Inertia.Controller
  import Plug.Conn

  def authenticate_user(conn, _opts) do
    user = get_user_from_session(conn)
    conn
    |> assign(:user, user) # Store in conn assigns
    |> assign_prop(:user, serialize_user(user)) # Pass to Inertia
  end
end

SSR requires Node.js to be installed on your production server. If using Docker, ensure nodejs is installed and set the NODE_ENV environment variable to production. Setting NODE_ENV=production is critical as it ensures the SSR script is cached in memory, preventing slow page rendering times.

# Example Dockerfile snippet
FROM ${RUNNER_IMAGE}

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

RUN curl -fsSL https://deb.nodesource.com/setup_x.x | bash - && \
    apt-get update && \
    apt-get install -y nodejs

ENV MIX_ENV="prod"
ENV NODE_ENV="production"

To manage the Node.js process pool, you must add Inertia.SSR to your application's supervision tree in lib/my_app/application.ex. You must provide the path option pointing to the directory containing your compiled ssr.js file (usually priv).

# lib/my_app/application.ex

defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    children = [
      # ... other children
      {Inertia.SSR, path: Path.join([Application.app_dir(:my_app), "priv")},
      MyAppWeb.Endpoint,
    ]
    Supervisor.start_link(children, strategy: :one_for_one)
  end
end

The library automatically sets the XSRF-TOKEN cookie. To ensure Phoenix can validate requests, you must configure your frontend Axios client to send the CSRF token using the x-csrf-token header name.

Add this configuration to your main JavaScript entry point (e.g., assets/js/app.js):

// assets/js/app.js
import axios from "axios";
axios.defaults.xsrfHeaderName = "x-csrf-token";

// the rest of your Inertia client code...