Summary

Second step of the @hono/inertia v3 protocol breakdown: ② Deferred props, built on top of the partial reload foundation from #1904.

Adds a defer(resolver, group?) helper. On the initial response the resolver is skipped and the prop key is advertised under page.deferredProps[group]. The Inertia client then issues one partial reload per group, at which point the resolver runs and the value is sent down — letting heavy data fetching happen after the page becomes interactive.

import { defer, inertia } from '@hono/inertia'

app.use(inertia())

app.get('/', (c) =>
  c.render('Dashboard', {
    user: { id: 1 },                       // sent on initial response
    posts: defer(() => fetchPosts()),      // fetched after mount
    stats: defer(() => fetchStats(), 'secondary'),
  }),
)

Multiple deferred props that share a group are fetched together in a single partial reload. The default group is "default".

Protocol behaviour

deferredProps is only emitted on the initial response; subsequent partial reloads strip it, so the client does not re-trigger the same group.

Implementation

• defer<T>(resolver, group = 'default'): T returns an opaque marker (Symbol.for('@hono/inertia/defer')) that the renderer unwraps. The return type is T, so call sites stay transparent and TypedResponse infers the awaited resolver type.
• The renderer loop now distinguishes three prop kinds — plain values, function-valued props (from feat(inertia): add partial reloads support with lazy function props #1904), and deferred markers — and decides on a single sync/async path based on whether any resolver needs awaiting. The non-deferred sync path is preserved when no async work is needed.
• PageObject gains an optional deferredProps?: Record<string, string[]> field, only present on the initial response when at least one prop was deferred.

Scope intentionally kept small (single PR per protocol feature, like #1904):

• ✅ Top-level defer() markers
• ✅ Multiple groups + default group
• ✅ Skip on initial, resolve on requested partial
• ❌ Nested / dot-path deferred markers — separate PR
• ❌ merge / prepend / deepMerge / always(fn) / infinite scroll markers — separate PRs (③④⑤ in the breakdown)

Test plan

• yarn workspace @hono/inertia test (28 passed, 9 new tests covering initial skip / group emission / partial resolve / only filter / JSON request / mixed deferred + function props / no-defer no-emit / non-XHR HTML visit)
• eslint packages/inertia clean
• prettier --check clean
• tsc -b clean
• tsdown build success