WhenMounted and BigInt in Inertia 3.8

Keeping browser-only code out of the server render

Charts, maps, and editors often need window, document, or viewport measurements while rendering. With SSR enabled, that can break the first response because those browser APIs do not exist in Node. The usual alternatives have been moving logic into a lifecycle hook, disabling SSR for a page, or adding a custom workaround for each dependency.

Inertia 3.8 adds WhenMounted to isolate that issue to a specific component. Its children render after the application mounts in the browser, while the server render and initial hydration use a fallback. That keeps SSR available for the rest of the page and makes the initial browser output match the server HTML. (inertiajs.com)

A Vue example

In Vue, the component comes from @inertiajs/vue3, and the alternative content is provided through the fallback slot. It is useful when a dependency needs browser APIs during rendering itself, rather than only inside an event handler or onMounted. I would make the placeholder close to the final component’s dimensions to avoid a noticeable layout shift after hydration.

<script setup>
import { WhenMounted } from '@inertiajs/vue3'
import SalesChart from '@/Components/SalesChart.vue'
</script>
 
<template>
  <WhenMounted>
    <template #fallback>
      <div class="h-64">Loading chart…</div>
    </template>
 
    <SalesChart />
  </WhenMounted>
</template>

The fallback is shown on the initial server-rendered load and during hydration. On later SPA visits, and in applications without SSR, Inertia renders the children immediately. That avoids showing the loading state again every time someone navigates through the application. (inertiajs.com)

Large IDs without silent rounding

The other practical addition concerns integers outside JavaScript’s safe range. A 64-bit ID or Snowflake value can leave PHP as a JSON number and lose precision before a component ever receives it. Inertia can now preserve those values and revive them as native BigInt values in the client. (inertiajs.com)

The feature is disabled by default and is configured on the server. I can enable it globally in config/inertia.php, use the INERTIA_PRESERVE_BIG_INTEGERS environment variable, or target individual responses with preserveBigIntegers(). For an application where only a few screens deal with this kind of identifier, the per-response approach is usually the cleaner choice.

return [
    // ...
    'preserve_big_integers' => true,
];

return Inertia::render('Orders/Show', [
    'order' => $order,
])->preserveBigIntegers();

When a value exceeds the safe range, Inertia sends it through a marker and the client rebuilds it as a BigInt. Regular integers still arrive as number, so the same prop may have either type depending on its value. Frontend code should account for that in comparisons, conversions, and formatting logic that assumes every ID is a normal JavaScript number. (inertiajs.com)

The fine print

WhenMounted does not remove the wrapped component or its dependencies from the SSR bundle. The module is still imported on the server, so a library that crashes at import time is not fixed just by wrapping its component. In that situation, the dependency needs an SSR-safe import path, a different loading strategy, or better isolation. (inertiajs.com)

Big integer preservation does not turn every numeric value in the application into a BigInt. It only affects integers outside JavaScript’s safe range, and useHttp does not handle BigInt values automatically for third-party API calls. When sending one of those values outside the Inertia router, forms, or Precognition, I would convert it to a string explicitly. (inertiajs.com)

• Source: Laravel News
• Official Inertia documentation
• Official Big Integers documentation