Inertia Bundle Laravel Package

Getting Started

• Install the package and make sure its Inertia middleware is in the web group so XHR visits get the Inertia response path (including the errors prop serialization and X-Inertia-* headers).
• Read docs/props.md first — it is the canonical description of prop types (merge, prepend, deepMerge, defer, scroll, once, optional) and now explicitly documents that X-Inertia-Reset makes the client replace the prop value rather than merge into it.
• The most useful first use case is a paginated/infinite-scroll list: return a merge() or scroll prop for the collection, and wire a filter form to router.reload({ reset: ['items'] }) so changing filters starts a fresh page instead of appending to the previous one.
• If you are migrating from inertia-laravel, read the "known gaps with inertia-laravel 3.x" file (CLAUDE.md / AGENTS.md) before writing code — it is the fastest way to know which behaviors are intentionally not covered yet.

Implementation Patterns

• Merge props + reset. Use merge() for load more style data and always give the client a reset path (reset: ['items']). After v3.1.1 the reset key is stripped from mergeProps/prependProps/deepMergeProps/matchPropsOn, so the client replaces the value on the first response — this is what makes "clear filters" behave correctly.
• Deferred and scroll props. The same reset semantics apply to deferred-merge and scroll props. For scroll specifically the package still emits scrollProps.<key>.reset, so you can drive an infinite-scroll container entirely from the header metadata without extra client state.
• once()->until(...) for expensive or shared props. Use this for values that should be resolved once and then handed to the client for a bounded time (config, permissions, feature flags). The expiry is now expressed in milliseconds, matching what the client compares against Date.now().
• optional() instead of lazily. lazy()/LazyProp is gone; anywhere you would have used it, use optional(). This is the one API rename that will bite code copied from older inertia-laravel docs.
• Errors prop. Treat the shared errors prop as an object, even when empty. In your Vue/React layer prefer Object.keys(errors).length over Array.isArray(errors) or .length on the raw value.
• Integration tip. Keep a thin shared PropsResolver-like service of your own for props you reuse across controllers, and write feature tests against the raw JSON payload (mergeProps, onceProps, scrollProps) rather than only rendering the page — that is where the protocol-level bugs in this release lived.

Gotchas and Tips

• Workaround removal. If you previously "fixed" once()->until() by dividing the expiry before sending it (because the client immediately re-resolved the prop), delete that workaround. onceProps.*.expiresAt is now milliseconds; the old conversion would make the prop look valid essentially forever.
• errors empty shape. Empty errors now serialize as {} on XHR, first visits and the Serializer path, matching inertia-laravel's (object) []. Any client code doing errors.map(...), errors.length, or Array.isArray(errors) will break on empty errors — audit for that before upgrading.
• Reset key must match the prop name exactly, including nested keys for deepMerge. A typo silently disables the reset and you are back to appending/merging into stale data.
• Don't rely on reset keys appearing in the merge descriptors. After v3.1.1 the key is intentionally omitted from mergeProps/prependProps/deepMergeProps/matchPropsOn; if your own tooling inspects those arrays to detect resets, switch to X-Inertia-Reset.
• Debugging protocol issues: capture the raw Inertia JSON response and compare the mergeProps, onceProps, scrollProps and X-Inertia-Reset entries against a minimal inertia-laravel app. The contributor docs explicitly track where this package still differs from inertia-laravel 3.x — check that list before filing a bug.
• Contributor/code style: tests are named camelCase to match php-cs-fixer; follow that when adding tests, and don't reintroduce lazy() references in docs.
• Upgrade risk: v3.1.1 is a patch with no breaking changes, so the risk is limited to apps that depended on the old (buggy) behavior — i.e. seconds-based expiresAt, array-shaped empty errors, or reset keys merging instead of replacing.