$ show inertiajs/inertia-phoenix
This repository is the official Elixir/Phoenix server-side adapter for Inertia.js (v3). It enables Phoenix developers to build modern server-driven single-page applications without constructing a separate JSON API. The library intercepts HTTP requests via a Plug, detects Inertia.js headers, and renders page data as JSON for XHR requests or embeds it in an HTML template for the initial load. It handles asset versioning (409 responses), partial reloads, server-side rendering (SSR) via a Node.js worker pool, and provides a rich set of controller helpers for managing props (deferred, shared, once, scroll, merge, etc.). The architecture is centered around a core Plug (`Inertia.Plug`), controller macros (`Inertia.Controller`), HEEx components (`Inertia.HTML`), an SSR supervisor (`Inertia.SSR`), and a Mix task for scaffolding (`inertia.install`). It achieves extensibility through Elixir protocols for pagination (`Inertia.Paginated`), error handling (`Inertia.Errors`), and SSR adapters (`Inertia.SSR.Adapter`), allowing seamless integration with libraries like Scrivener, Flop, and Ecto. The codebase exhibits high craftsmanship. The prop resolution engine in `controller.ex` uses a sophisticated system of tagged tuples and recursive resolution to handle lazy evaluation, caching, merging, and transformation—a non-obvious and elegant functional pattern. The SSR adapter pattern cleanly isolates the Node.js worker pool management behind a behaviour. The testing module provides comprehensive helpers for integration testing. The library is actively maintained, tracks upstream Inertia.js changes (Laravel parity), and uses modern Elixir/Phoenix conventions. This library is ideal for Phoenix teams who want the development speed of a modern SPA framework (React, Vue, Svelte) with the server-side control and simplicity of a traditional server-rendered application. It eliminates the need for a dedicated frontend API layer while providing features like partial page rendering, lazy-loaded components, and server-side rendering for SEO and initial load performance.
The LLM identified 4 files worth highlighting for reuse:
The core prop resolution engine. Defines a rich type system using tagged tuples (`{:defer, ...}`, `{:once, ...}`, `{:scroll, ...}`, `{:merge, ...}`, etc.) and a recursive resolver. This allows complex prop shapes with lazy evaluation, caching, merging, and transformation. It is a highly reusable pattern for any data pipeline requiring composable data transformations.
Implements a pluggable adapter pattern for server-side rendering. The `Inertia.SSR.Adapter` behaviour defines the contract, and `NodeJSAdapter` provides a concrete implementation using a pool of Node.js workers managed by an OTP supervisor. This pattern is cleanly isolated and could be extracted for any Elixir project needing to delegate rendering to an external runtime.
Defines Elixir protocols for serializing validation errors and pagination metadata. Provides built-in implementations for `Ecto.Changeset`, `Scrivener.Page`, and `Flop.Meta`. This is a textbook example of using protocols for polymorphism, allowing the library to integrate with multiple external libraries without tight coupling.
A well-designed module providing helper functions for testing Inertia responses in Phoenix controller tests. Functions like `inertia_page/1`, `inertia_props/1`, `inertia_flash/1` extract Inertia-specific data from a `Plug.Conn`, enabling thorough integration testing without a browser. This pattern is directly reusable for any library that modifies the HTTP connection.