Inertia.js Laravel Adapter

inertia-laravel is the Laravel-side half of Inertia.js, a protocol for building single-page applications using classic server-side routing and controllers instead of a client-side router or API. It lets Laravel controllers return page components (Vue, React, or Svelte) directly via Inertia::render(), while the adapter handles the request/response protocol, shared data, validation error forwarding, asset versioning, and optional server-side rendering.

The package registers itself as a Laravel service provider, adding middleware that intercepts Inertia-flavored requests, a Response class that builds the JSON page-object payload Inertia’s client expects, and Artisan commands for scaffolding and running the SSR server — letting teams build modern reactive frontends without maintaining a separate API layer.

What You Get

• An Inertia::render() helper and Response class that serialize page components and props into the JSON protocol Inertia’s client understands
• Middleware that manages asset versioning, shared data, and full vs. partial (XHR) page visits automatically
• Prop helpers for lazy (OptionalProp), always-included (AlwaysProp), deferred (DeferProp), and mergeable (MergeProp) data, giving fine-grained control over what’s sent on each request
• Built-in server-side rendering (SSR) support via an inertia:start-ssr Artisan command and SSR gateway/bundle configuration
• A Testing module (InertiaResponse, assertions) for asserting props and component names in Laravel’s HTTP test suite

Common Use Cases

• Building a Laravel-backed SPA with Vue, React, or Svelte without hand-rolling a JSON API
• Migrating a traditional Blade/server-rendered Laravel app to a modern reactive frontend incrementally
• Apps that need SSR for SEO/performance but want to keep all business logic and routing in Laravel controllers
• Teams that want Laravel’s validation, auth, and session handling to flow directly into frontend components without duplicating logic in a separate API

Under The Hood

Architecture — the package registers Inertia\ServiceProvider (src/ServiceProvider.php) which binds the Inertia facade, publishes config/stubs, and wires an HTTP Middleware (src/Middleware.php) that intercepts every request: on first load it renders a root Blade view embedding the serialized page object, on subsequent XHR visits it returns just the JSON payload, using an X-Inertia header and version hash to decide which. Response (src/Response.php) resolves the props tree — including lazy OptionalProp, DeferProp, MergeProp, and AlwaysProp wrappers via PropsResolver/ResolvesCallables — into the final JSON structure the JS-side adapters expect. Tech Stack — plain PHP 8.2+ targeting Laravel 11/12/13 and Symfony Console 7/8 for its Artisan commands, with an Ssr/ subpackage that shells out to a Node-based SSR bundle when server-side rendering is enabled. Code Quality — a tests/ directory mirrors the src/ structure (including a dedicated Testing/ helper module for asserting Inertia responses in Laravel’s HTTP test client), enforced by PHPUnit, Larastan (PHPStan for Laravel) static analysis, and Laravel Pint for style, all wired into composer.json scripts (test, lint, analyze). API Design — the public surface is intentionally small: Inertia::render() mirrors Laravel’s view() helper almost exactly, keeping the learning curve low for Laravel developers, while prop-wrapper classes (Deferrable, Mergeable, Rescuable) provide an escape hatch for advanced partial-reload and streaming-prop use cases without complicating the common case.