Inertia.js partial reload shallow merge replaces nested objects entirely

Answer

1. No built-in deep merge exists. Inertia partial reloads merge page.props at the top level only. The only array accepts top-level prop keys; there is no supported dot-notation path such as user.profile.settings, and no configuration flag for recursive merging.
2. Do not mutate page.props in onBefore or onSuccess. These hooks are for visit interception and side effects. Forcing a deep merge there is unsupported and can desynchronize client page state from the server response.
3. Inertia 2.0 native deep merging is unconfirmed. Treat it as unresolved and implement your own layer if needed.

Confirmed behavior and assumptions

Confirmed: Inertia v1 clients shallow-merge top-level props. If only: ['user'] returns { user: { profile: { settings: { } } } }, the previous user.profile.preferences is replaced or removed because the entire user key is overwritten. preserveState: true keeps the component mounted but does not change this merge.

Assumption: you use a stable Inertia v1 adapter such as @inertiajs/vue3, @inertiajs/react, or @inertiajs/svelte. Pre-release v2 builds and community forks may differ.

Steps for this case

1. Return the complete parent object from the partial-reload endpoint, including sibling keys the client expects to retain, such as preferences.
2. If the server cannot return the full parent, maintain a client-side normalized store and merge the incoming partial after Inertia updates page.props.
3. Confirm the installed adapter version before relying on hook-based workarounds.

Verification

Open DevTools Network, trigger Inertia.visit({ only: ['user'] }), and inspect page.props.user.profile before and after. Confirm whether preferences disappears.

Run this scoped check:

grep -E 'inertiajs' package.json

One missing diagnostic detail

Which Inertia client adapter and exact version are you using? This changes the recommendation because v1 adapters and pre-release v2 builds may differ, and some community forks have experimented with deep-merge plugins.