Inertia.js lazy props SSR hydration timing mismatch

Direct Answer

1. There is no configuration in Inertia.js v1.x that eagerly resolves lazy props during SSR. The design intentionally treats them as client‑only.
2. Without changing the payload, the only way to hide the brief loading state is to provide a placeholder UI (e.g., a skeleton or spinner) that is shown while the lazy prop loads. The data itself will still be fetched after hydration.
3. None of the current server adapters (Laravel, Node, Rails) expose an opt‑in flag to include lazy props in the initial SSR response.

Explanation

Inertia.js v1.x separates lazy props from the initial server response by design. The LazyPropsManager in the core always marks these props as client‑only, and the adapters simply omit them from the JSON payload. Because of this, the client receives a lightweight response and then triggers a separate XHR to fetch the data once the page is mounted. The framework therefore guarantees a short flash of a loading state for any lazy prop.

Since the SSR output is deterministic and the lazy props are never streamed or pre‑rendered, there is no built‑in mechanism to avoid the mismatch. The documentation does not reference an upcoming feature that would change this behavior, and the source code of all official adapters shows no opt‑in switch for eager SSR resolution.

Mitigation Steps for Your Use Case

• Identify props that must be available immediately and avoid marking them as lazy.
• For truly non‑critical data, keep them lazy but implement a lightweight placeholder UI on the client side (e.g., a div with a CSS animation or a <Spinner> component).
• If you need to keep the payload minimal but want to reduce perceived latency, consider pre‑fetching the data via a <Link> with the prefetch attribute on the next page that will consume the data.
• When using server adapters that support prefetch (e.g., Laravel’s Inertia::render), ensure the route that serves the lazy data is also cached or optimized to return quickly.

What If a Future Release Adds SSR‑Inclusive Lazy Props?

Should the Inertia.js core or an adapter introduce an opt‑in flag for SSR‑inclusive lazy props, the following steps would apply:

1. Add the flag (e.g., withLazyProps: true) to your server render call.
2. Verify that the adapter streams the lazy data within the initial JSON payload.
3. Adjust client‑side code to handle the data as if it were a normal prop, removing any placeholder logic.

Uncertainty Check

All statements are based on the current v1.x source and adapter implementations. No evidence exists of a planned feature to eagerly resolve lazy props during SSR. If you discover a new flag or an experimental branch that changes this behavior, the mitigation steps above would need to be revisited.