Inertia.js 2.0.12 : Les Once Props pour des données partagées optimisées

La version 2.0.12 d’Inertia Laravel introduit les Once Props, une fonctionnalité attendue pour optimiser la gestion des données partagées. Fini le rechargement systématique de données statiques à chaque navigation : le client les mémorise désormais automatiquement.

Présentation des Once Props

Les Once Props répondent à un problème récurrent dans les applications Inertia.js : le transfert répété de données qui changent rarement. Liste des pays, plans tarifaires, permissions utilisateur… Ces données étaient jusqu’ici envoyées à chaque requête, même si elles restaient identiques.

Avec Inertia::once(), ces props sont évaluées une seule fois côté serveur. Le client les conserve en mémoire et les réutilise lors des navigations suivantes. Le gain en performance est immédiat : moins de calculs serveur, moins de données transférées.

Cette fonctionnalité a été publiée le 9 décembre 2025 dans la version 2.0.12 du package inertiajs/inertia-laravel.

Installation et configuration

Assurez-vous d’utiliser la dernière version du package Laravel :

composer require inertiajs/inertia-laravel:^2.0

Le package requiert Laravel 10+ et PHP 8.1 minimum. Côté client, mettez également à jour votre adapter Vue, React ou Svelte vers la version 2.x.

Utilisation basique avec Inertia::once()

La méthode Inertia::once() s’utilise exactement comme les autres méthodes de props, avec un callback retournant les données :

<?php

namespace App\Http\Controllers;

use App\Models\Plan;
use Inertia\Inertia;

class BillingController extends Controller
{
    public function index()
    {
        return Inertia::render('Billing', [
            // Cette prop ne sera évaluée qu'une seule fois
            'plans' => Inertia::once(fn () => Plan::all()),
            // Les autres props restent classiques
            'currentSubscription' => auth()->user()->subscription,
        ]);
    }
}

Lors de la première visite, le callback est exécuté et les données envoyées au client. Sur les visites suivantes vers une page incluant cette même prop, le serveur ignore le callback et n’inclut pas la prop dans la réponse. Le client utilise la valeur mémorisée.

Partager des Once Props globalement

Le cas d’usage le plus puissant : les données partagées sur toutes les pages. Configurez-les dans votre middleware HandleInertiaRequests :

<?php

namespace App\Http\Middleware;

use App\Models\Country;
use Illuminate\Http\Request;
use Inertia\Inertia;
use Inertia\Middleware;

class HandleInertiaRequests extends Middleware
{
    public function share(Request $request): array
    {
        return array_merge(parent::share($request), [
            // Méthode classique : via Inertia::once()
            'countries' => Inertia::once(fn () => Country::all()),
        ]);
    }

    // Méthode alternative dédiée aux Once Props
    public function shareOnce(Request $request): array
    {
        return array_merge(parent::shareOnce($request), [
            'timezones' => fn () => config('app.timezones'),
            'locales' => fn () => config('app.available_locales'),
        ]);
    }
}

La méthode shareOnce() offre une syntaxe plus concise : pas besoin d’encapsuler avec Inertia::once(), le middleware s’en charge.

Gérer l’expiration et le rafraîchissement

Les données finissent par devenir obsolètes. Plusieurs mécanismes permettent de contrôler quand les rafraîchir.

Définir une durée d’expiration

<?php

use App\Models\ExchangeRate;
use Inertia\Inertia;

return Inertia::render('Dashboard', [
    // Rafraîchit automatiquement après 24 heures
    'rates' => Inertia::once(fn () => ExchangeRate::all())
        ->until(now()->addDay()),
]);

La méthode until() accepte un DateTimeInterface, un DateInterval, ou un nombre de secondes.

Forcer le rafraîchissement côté serveur

<?php

use App\Models\Plan;
use Inertia\Inertia;

return Inertia::render('Billing', [
    // Force le recalcul de la prop
    'plans' => Inertia::once(fn () => Plan::all())->fresh(),

    // Rafraîchissement conditionnel
    'features' => Inertia::once(fn () => Feature::active()->get())
        ->fresh($request->has('refresh')),
]);

Rafraîchir depuis le client

Un partial reload côté JavaScript force le serveur à réévaluer la prop :

// Vue 3 avec Inertia
import { router } from '@inertiajs/vue3'

// Rafraîchit uniquement la prop 'plans'
router.reload({ only: ['plans'] })

Partager une prop sous différents noms

Parfois, la même donnée est utilisée sur plusieurs pages avec des noms différents. La méthode as() permet de définir une clé commune :

<?php

use App\Models\Role;
use Inertia\Inertia;

// Page liste des membres
return Inertia::render('Team/Index', [
    'memberRoles' => Inertia::once(fn () => Role::all())->as('roles'),
]);

// Page d'invitation
return Inertia::render('Team/Invite', [
    'availableRoles' => Inertia::once(fn () => Role::all())->as('roles'),
]);

Les deux pages partagent la même valeur en mémoire grâce à la clé roles. La prop n’est évaluée que sur la première page visitée.

Combiner avec d’autres types de props

Les Once Props se combinent avec les Deferred Props, Merge Props et Optional Props :

<?php

use App\Models\Permission;
use App\Models\Category;
use Inertia\Inertia;

return Inertia::render('Dashboard', [
    // Chargé en différé ET mémorisé
    'permissions' => Inertia::defer(fn () => Permission::all())->once(),

    // Fusionné avec les valeurs existantes ET mémorisé
    'activity' => Inertia::merge(fn () => $user->recentActivity())->once(),

    // Optionnel (partial reload only) ET mémorisé
    'categories' => Inertia::optional(fn () => Category::all())->once(),
]);

Points d’attention

• Oubli automatique : naviguer vers une page sans la Once Prop efface sa valeur mémorisée. Au retour, elle sera recalculée.
• Prefetching compatible : les Once Props fonctionnent avec le prefetching d’Inertia 2.0. Les pages préchargées contenant une Once Prop expirée sont automatiquement invalidées.
• Données sensibles : évitez les Once Props pour des données qui doivent être vérifiées à chaque requête (permissions temps réel, quotas…).
• Debugging : en développement, pensez à utiliser fresh() ou les DevTools pour vérifier que vos props se comportent comme attendu.

Conclusion

Les Once Props comblent un vide dans l’écosystème Inertia.js. Pour les listes de référence, configurations, et données rarement modifiées, cette fonctionnalité réduit significativement la charge serveur et le volume de données transférées. La combinaison avec shareOnce() dans le middleware en fait un outil particulièrement adapté aux données globales comme les pays, devises ou traductions.

Ressources

• Documentation officielle Once Props
• Release v2.0.12 sur GitHub
• Pull Request #793 – Support for once() props
• Documentation Shared Data