inertia-laravel: the small adapter that decides who renders a page

A README that refuses to describe the library

The README for this package is unusually short, and the omission is deliberate rather than an oversight. It opens with three badges: latest release, build status from the tests workflow, and total downloads from Packagist. Then it says to visit inertiajs.com to learn more. After that come three administrative sections, Contributing with a pointer to the contribution guide, a Code of Conduct section pointing at Laravel's, a security policy notice, and the MIT license statement.

There is no install command, no usage example, no configuration sample and no description of what the package does. That is the correct behaviour for an adapter in a larger ecosystem. The documentation lives at inertiajs.com, which is also the declared homepage, and duplicating it in the repository would create a second place to keep in sync.

It does have one practical consequence. If you are deciding whether to adopt this package, the README gives you nothing to evaluate. You have to look at the repository layout, the changelog and the releases instead, which is what the rest of this article does.

What the repository layout reveals

The tree is compact and tells you where the package draws its boundaries. `src/` is the adapter itself. `config/` holds the published configuration file, `resources/` holds views and language files, and `stubs/` holds the scaffolding templates used when the package is installed into an application, which is how a Laravel package can create directories and assets in the host project. `helpers.php` sits at the root as a globally included function file.

Then there is the tooling, and it is worth noting because it says what the project considers non-negotiable. `phpstan.neon` for static analysis, `phpunit.xml.dist` for the test configuration, and `pint.json` for Laravel Pint, the code style fixer. `composer.json` is the package definition, `CHANGELOG.md` the history, `LICENSE.md` the license text.

A package with static analysis, a test suite and a pinned style tool has the maintenance habits of a Laravel-adjacent project that expects to run in continuous integration on many Laravel versions. That is also visible in the releases: the 3.x and 2.x lines are being patched in parallel.

The repository has 2,478 stars and 289 forks with only 4 open issues, which is a low ratio for a package with this many installations. The default branch is 3.x, the language is PHP, and the last push was on 2026-09-25.

Redirects, deferred callbacks and the back() return type

The most instructive release is v3.4.0, published 2026-09-25. Five changes went in, and each one marks a place where a server-rendered app and a client-side router have to agree.

The first is that `back()` now returns Illuminate's `RedirectResponse`. This is a type-level change to a helper everyone uses, and it matters because it gives you the full Laravel response API rather than something narrower. When you are inside an Inertia request, calling `back()` needs to produce something the Inertia middleware can interpret as a redirect while still being a normal Laravel response.

The second and third are about server-side rendering. One change lets you configure the HTTP request sent to the SSR server, which is the practical consequence of SSR being a separate Node process that your PHP application calls over HTTP. If that request needs a header, a timeout or a different host, you now have a setting for it rather than editing the adapter. The other ensures deferred callbacks run on Inertia redirects.

Deferred props are a way to defer part of a page payload, and a redirect can wipe out the context those deferred callbacks were scheduled in. That the fix was needed at all says the two mechanisms interact in ways that are easy to miss.

The fourth change adds a `--graceful` option to the `inertia:stop-ssr` Artisan command. That command stops the long-running SSR process, and a graceful option is exactly what you want in a deploy where the process should finish in-flight requests rather than being killed mid-render.

Why the initial page payload needed escaping

Version 3.3.4, published 2026-09-11, contains a single change: escaping HTML tags in the initial page JSON. That one line is the clearest statement of what this adapter's job actually is.

With server-side rendering, the first response a browser receives is HTML rendered by the Node process, not by Blade. Laravel still has to supply the page's data, and that data has to reach the browser as JSON embedded in the document. Without escaping, any string in your page props containing something that looks like a closing script tag can terminate that block early, which is a straightforward way to inject markup into a page your own application generated. Escaping the tags before embedding the JSON closes the gap.

The fix landed in 3.3.4 on the 3.x line, and the shape of it says something about how the project handles such issues. It is a patch release for a change that touches the security boundary, not a minor release.

Taken with the rest of the 3.4.0 changes, the picture is of an adapter whose hard problems are all about boundaries: HTML into JSON, an HTTP request across a process boundary, a redirect that has to preserve deferred work, and a long-running server that has to shut down politely.

Two version lines and a healthy contributor base

On 2026-09-25 the project shipped both v3.4.0 and v2.0.28 within minutes of each other. The 2.0.28 release is a single backport: the `--graceful` option for `inertia:stop-ssr`, credited to a different contributor, @TimKunze96, who did the equivalent work on the 2.x branch while @pascalbaljet handled it on 3.x.

Running two major lines in parallel means a large installation base is still on 2.x, and it means a maintainer has to decide which fixes are worth backporting. That the project shipped a fix to both lines the same day is a good sign, and it also means the constraint you write in composer.json matters. A constraint that says 3.x gets SSR request configuration and previous-location storage; a constraint on 2.x does not.

The contributors credited in these releases are worth noting for a different reason. v3.4.0 credits two first-time contributors, @YannikFirre for the `back()` return type and @drewmt for storing previous locations for Inertia visits. A small package that is turning new contributors into merged pull requests within its current release cycle is a healthy project.

The repository is MIT licensed, not archived, on the 3.x default branch, with 4 open issues, 2,478 stars and 289 forks. Everything about how to use it is on inertiajs.com; the changelog is where the design decisions are legible.

Editorial conclusion

inertia-laravel is best understood as a negotiation layer rather than a component library, and its release history shows exactly where the negotiation gets interesting: server-side rendering, redirects that have to run deferred callbacks, and the escaping of HTML in the initial page payload. Its README will not help you evaluate any of that, since it is four sections of badges and links, so the repository layout and the changelog are the better guide. Two version lines are maintained in parallel right now, 3.x and 2.x, which is worth noting before you pick a constraint in composer.json. The default branch is 3.x, MIT licensed, with version 3.4.0 released on 2026-09-25 and a last push the same day.

Frequently asked questions

Official sources

1. inertiajs/inertia-laravel on GitHub
2. License: MIT
3. Project website
4. README
5. Releases