WhenMounted and BigInt Props in Inertia.js v3.8

The Inertia.js team released v3.8.0 with a WhenMounted component for rendering browser-only code under server-side rendering, opt-in support for integers beyond JavaScript's safe range as native BigInt values, and more:

# WhenMounted for Browser-Only Components

Evan Burrell 贡献了一个 WhenMounted component for the React, Vue, and Svelte adapters. A component that reads window 或者 document while rendering crashes server-side rendering with a "window is not defined" error.

这 WhenMounted component renders its fallback on the server and its children once the component has mounted in the browser:

进口
{ WhenMounted }
从

'@inertiajs/vue3'

<
模板
>
<
WhenMounted
>
<
SalesChart
/>
<
模板
#
倒退
>
<
页
>Loading chart...</
页
>
</
模板
>
</
WhenMounted
>
</
模板
>

In React, pass the children as a function so the browser-only code does not run on the server, since JSX children are evaluated before the component renders:

进口
{ WhenMounted }
从

'@inertiajs/react'
<
WhenMounted

倒退
=
{<
页
>Loading chart...</
页
>}>
{()
=>
<
SalesChart

宽度
=
{window.innerWidth} />}
</
WhenMounted
>

The fallback shows only during SSR and the first hydration render, so the browser's first render matches the server HTML and there is no hydration mismatch. A WhenMounted that mounts later, such as after a client-side visit, renders its children right away.

看 #3218 更多细节。

# Big Integers as Native BigInt Values

帕斯卡·巴尔杰特 added support for integers outside JavaScript's safe integer range. PHP sends a 64-bit integer, such as a Snowflake ID, as a JSON number, and the browser rounds it when parsing the page, so 900719925474099988 变成 900719925474100000 with no error.

The feature is opt-in on the server and needs inertia-laravel v3.5.0 . Turn it on for every response with the preserve_big_integers 选项 config/inertia.php （或 INERTIA_PRESERVE_BIG_INTEGERS environment variable), or for a single response:

返回

惯性
::
使成为
（
'Orders/Show'
，[

'ID'

=>
$订单
->
ID，
]）
->
preserveBigIntegers
（）；

The adapter encodes large integers as { "$bigint": "..." } markers, and the client turns them back into BigInt values. Integers inside the safe range stay regular numbers:

定义Props
({ id:
BigInt
}）

<
模板
>
<
页
>Order {{ id }}</
页
>

<!-- Order 900719925474099988 -->
</
模板
>

This works for the initial page, visits, partial reloads, encrypted history, and SSR. A BigInt sent back through the router, a form, or Precognition is submitted as a string of digits, which Laravel's integer validation rule and $request->integer() accept.

看 #3237 更多细节。

# Form Forwards Error and Flash Callbacks

Dale Weaver fixed the <Form> component so it passes onHttpException , onNetworkError , onBeforeUpdate ， 和 onFlash to the visit. These callbacks were already part of the component's props, but the adapters never forwarded them, so an HTTP 500 or a network failure on a <Form> submission never called them. They now work the same as on useForm , and returning false from either error callback stops the global event and the default handling:

<Form
action="/orders"
method="post"
@http-exception="(response) => { toast.error('Something went wrong'); return false }"
>

看 #3262 更多细节。

# Out-of-Order Optimistic Responses

Pascal Baljet fixed a case where two optimistic updates were in flight and the first request's response arrived last. Its props were read before the second write, so applying them rolled the second update back on screen. The page then disagreed with the server until the next visit.

Optimistic requests now carry an ID, and a response is ignored when a later optimistic request has already succeeded. A failed request does not count, so an older successful response still updates the page after a newer request fails and rolls back.

看 #3245 更多细节。

# History Restores After a Deploy

Lazizbek Ergashev fixed back and forward navigation across a deploy. When the browser reloaded the document on a back or forward navigation, Inertia restored the page from history state without checking its asset version. The new JavaScript bundle then rendered props from the previous deploy, and a prop added or renamed since then was undefined . Inertia now compares the versions and renders the freshly loaded page when they differ.

看 #3264 更多细节。

# 发行说明

You can see the complete list of changes below and the diff between 3.7.1 and 3.8.0 在 GitHub 上。以下发行说明直接来自 GitHub release :

# v3.8.0

• [3.x] Fix multi-byte UTF-8 corruption in SSR request body parsing by @onk 在 #3248
• Bump pnpm/action-setup from 6.0.10 to 6.1.0 in the github-actions group by @dependabot 在 #3261
• [3.x] Fix core types when Axios is not installed by @fouteox 在 #3258
• [3.x] Compare asset versions before restoring history on a back/forward reload by @lazerg 在 #3264
• [3.x] Prevent a stale optimistic response from reverting a newer optimistic update by @pascalbaljet 在 #3245
• [3.x] Prefer server.origin when resolving SSR CSS link URLs by @pascalbaljet 在 #3268
• [3.x] Avoid top-level await in the generated SSR bundle by @ramonmalcolm10 在 #3239
• [3.x] Forward missing Form visit callbacks by @daleweaver777 在 #3262
• [3.x] Add WhenMounted component by @埃文-伯勒尔 在 #3218
• [3.x] Improve tests in CI by @pascalbaljet 在 #3277
• [3.x] Bump dependencies by @pascalbaljet 在 #3278
• [3.x] Clean up in-flight cancelled prefetches by @gianpieropuleo 在 #3271
• [3.x] Handle already-aborted signals in the XHR client by @gianpieropuleo 在 #3273
• [3.x] Fix React InfiniteScroll scroll jump on Safari and CI flakiness by @pascalbaljet 在 #3282
• [3.x] Support big integers as native BigInt values by @pascalbaljet 在 #3237
• [3.x] Bump dependencies by @pascalbaljet 在 #3286
• [3.x] Silence state_referenced_locally warning in Svelte App 组件 @pascalbaljet 在 #3287