WhenMounted y BigInt en Inertia 3.8
Inertia 3.8 evita errores de SSR con componentes de navegador y conserva IDs grandes sin perder precisión.
Por Isma4 min de lectura
Aislar el código que no puede ejecutarse en el servidor
Un gráfico, un mapa o un editor pueden necesitar window, document o las dimensiones del viewport durante el renderizado. Con SSR activado, ese acceso puede romper la respuesta inicial porque esas APIs no existen en Node. Hasta ahora, la salida habitual era retrasar lógica a un hook, desactivar SSR para una página o buscar una solución específica para cada dependencia.
Inertia 3.8 incorpora WhenMounted para acotar ese problema a un componente concreto. El contenido incluido dentro se renderiza cuando la aplicación ya se ha montado en el navegador, mientras que el servidor y la hidratación inicial muestran un fallback. Así se conserva SSR para el resto de la página y el HTML inicial coincide con el que espera el cliente al hidratar. (inertiajs.com)
Un ejemplo con Vue
En Vue, el componente se importa desde @inertiajs/vue3 y el contenido alternativo se define mediante el slot fallback. Es una solución razonable para una dependencia que necesita APIs del navegador en el propio renderizado, no solo dentro de un evento o de onMounted. El placeholder debería ocupar un espacio parecido al componente final si quiero evitar un salto visible cuando termine la hidratación.
<script setup>
import { WhenMounted } from '@inertiajs/vue3'
import SalesChart from '@/Components/SalesChart.vue'
</script>
<template>
<WhenMounted>
<template #fallback>
<div class="h-64">Cargando gráfico…</div>
</template>
<SalesChart />
</WhenMounted>
</template>El fallback aparece en la carga inicial renderizada en servidor y durante la hidratación. En visitas posteriores dentro de la SPA, y en aplicaciones sin SSR, Inertia renderiza directamente los hijos. Eso evita que el usuario vea el placeholder una y otra vez al navegar por la aplicación. (inertiajs.com)
IDs grandes sin redondeos silenciosos
La otra novedad práctica afecta a los enteros que superan el rango seguro de JavaScript. Un ID de 64 bits o un Snowflake puede llegar desde PHP como número JSON y perder precisión antes de que el componente lo reciba. Inertia puede preservar esos valores y convertirlos en BigInt nativos en el cliente. (inertiajs.com)
La opción está desactivada por defecto y se configura en el servidor. Puedo activarla globalmente en config/inertia.php, usando también la variable de entorno INERTIA_PRESERVE_BIG_INTEGERS, o limitarla a respuestas concretas con preserveBigIntegers(). Para una aplicación con pocos puntos que manejan este tipo de identificadores, prefiero la opción por respuesta.
return [
// ...
'preserve_big_integers' => true,
];return Inertia::render('Orders/Show', [
'order' => $order,
])->preserveBigIntegers();Cuando el valor excede el rango seguro, Inertia lo transporta con un marcador y el cliente lo reconstruye como BigInt. Los enteros normales siguen llegando como number, por lo que una misma prop puede tener uno u otro tipo según su valor. En el frontend conviene revisar comparaciones, conversiones y formatos que asuman siempre un número convencional. (inertiajs.com)
La letra pequeña
WhenMounted no elimina el componente ni sus dependencias del bundle de SSR. El módulo sigue importándose en el servidor, así que una librería que falla simplemente al ser importada no queda resuelta por envolver su componente. En ese caso toca buscar una importación compatible con SSR, cargarla de otra forma o separar mejor esa dependencia. (inertiajs.com)
La preservación de enteros grandes tampoco convierte todos los datos de la aplicación en BigInt. Solo afecta a los enteros fuera del rango seguro de JavaScript, y useHttp no gestiona valores BigInt automáticamente para llamadas a APIs de terceros. Si necesito enviar uno de esos valores fuera del router, de formularios de Inertia o de Precognition, lo convertiré explícitamente a cadena. (inertiajs.com)