Inertia Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy on the Inertia server adapter. This package is a from-scratch PHP implementation of the Inertia.js server-side protocol, with explicit parity goals against the official inertia-laravel adapter. That makes it a real alternative in a build/buy/fork evaluation rather than a thin wrapper — the decision is "standardise on the official adapter" vs. "adopt a parity-tracking alternative," not "write our own."
• Frontend architecture choices. Because it implements the protocol directly (X-Inertia-Reset, onceProps, mergeProps/deferredProps/scrollProps, the shared errors prop), it constrains and enables SPA patterns: partial reloads, merge/scroll pagination, deferred data loading, and once() props cached client-side. Choosing this package is implicitly choosing those patterns for the roadmap.
• Feature feasibility for specific UI work. once()->until() support means you can ship props that stay cached for a bounded window and only re-resolve after expiry — relevant for expensive computed data (permission maps, feature flags, config payloads) that shouldn't be re-serialised on every visit.
• Correctness expectations for existing behaviour. The X-Inertia-Reset fix changes observable client behaviour: router.reload({ reset: [...] }) now replaces rather than merges. Any roadmap item depending on "reload resets this list" was previously silently wrong; treat this as a behaviour contract, not a cosmetic patch.
• Migration/parity roadmap. The docs explicitly track "known gaps with inertia-laravel 3.x." That gap list is the roadmap artefact — it tells you what still blocks a full swap and how much risk sits between you and upstream parity.
• Not a decision this supports: nothing here touches auth, persistence, or infrastructure. This is a presentation-layer dependency; it should not be used to justify stack-level or vendor-level commitments.

When to Consider This Package

Consider it when:

• You are on Laravel/PHP with an Inertia.js frontend and the official inertia-laravel adapter does not fit — version constraints, conflicting transitive dependencies, or a Laravel version the official adapter has not yet caught up to.
• You need protocol-level control — custom prop resolution, bespoke serialization, or an alternative PropsResolver — and want an implementation you can read end-to-end rather than patch around.
• You are evaluating multiple server adapters (e.g. alongside inertia-laravel and inertia-rails/inertia-django) and want a comparison point for how faithfully the protocol is implemented, not just whether it "works."
• You require once() / deferred / merge / scroll prop semantics and are willing to validate them yourself against a reference implementation.

Look elsewhere when:

• Protocol stability is the priority. The release notes are a catalog of three behavioural divergences from inertia-laravel — reset semantics, an expiresAt unit mismatch that broke until() on every visit, and an empty-errors shape mismatch ([] vs {}). All three are the kind of bug that degrades user-visible behaviour without throwing an exception. That pattern argues for upstream, not for an alternative.
• You have no appetite for parity-tracking. The package documents its own gaps against inertia-laravel 3.x. If nobody on the team owns reading that gap list each release, the gaps become your incidents.
• You need vendor SLAs or long-term support guarantees. A single-maintainer package is a bus-factor risk for anything load-bearing.
• The official adapter already satisfies you — the default answer. Adopt this only with a specific reason, not by preference.
• You are not on Inertia or not on Laravel/PHP; nothing here transfers.
• You cannot pin and test — the expiresAt seconds-vs-milliseconds bug is exactly the class of defect that a version pin plus an integration test catches and code review does not.

How to Pitch It (Stakeholders)

For executives — one paragraph. This is a small, single-maintainer open-source PHP package that plugs the Inertia.js frontend framework into our Laravel backend. It is an alternative to the official connector, not a required component. The release under review is a patch: it fixes three bugs where this package disagreed with the official one — a list-reset that merged instead of replacing, a cache-expiry value in the wrong unit that made a caching feature silently never cache, and an empty-error response encoded as a list instead of an object. None are breaking; all are the sort of defect that fails quietly in production rather than loudly in CI. Recommendation: do not adopt this package as a new dependency on the strength of this release. If we already depend on it, upgrade and pin, and add a test asserting reset and once()->until() behaviour. If we do not, the official adapter remains the lower-risk default and there is no capability here we cannot get upstream.

For engineering — the short version. Patch release, no breaking changes, but three behaviour-visible fixes worth taking deliberately rather than incidentally:

1. X-Inertia-Reset keys are now stripped from mergeProps / prependProps / deepMergeProps / matchPropsOn, so partial-reload resets replace client state instead of merging into it. Covers merge, deferred-merge and scroll props; scrollProps.<key>.reset is still emitted. This aligns with inertia-laravel's PropsResolver — meaning prior versions of this package diverged, and any UI relying on reset-then-merge was leaning on the divergence.
2. once()->until() now emits expiresAt in milliseconds, matching the client's Date.now() comparison. Previously seconds, so every until() prop read as already expired and re-resolved on every visit. This was a performance regression masquerading as correctness — worth checking whether we attributed slow pages to something else.
3. Empty errors now serializes as {} rather than [] across XHR, first-visit and Serializer paths, matching the protocol and (object) [] upstream. Frontend code doing anything type-sensitive on errors should be re-checked.

Docs were also cleaned up: lazy() / LazyProp references removed (use optional()), and the known-gaps list against inertia-laravel 3.x is now explicitly documented — that list is the thing to read before planning any migration, and it is the clearest signal of how much parity work remains. Upgrade, pin, and cover items 1 and 2 with integration tests.