Inertia.js pour PHP : guide complet avec exemples concrets

1. Qu'est-ce que c'est et pourquoi l'utiliser ?

Inertia.js n'est ni un framework ni une bibliothèque pour créer des SPA (Single Page Application) au sens classique. C'est plutôt un « pont » ou un « adaptateur » qui permet de créer des applications modernes d'une seule page en utilisant un framework serveur classique (dans notre cas, Laravel sur PHP) et n'importe quel framework front-end moderne (React, Vue.js ou Svelte) sans avoir à écrire une API REST séparée.

Le principal problème que résout Inertia.js est l'abandon de l'approche traditionnelle « le serveur rend du HTML » ou « le serveur renvoie du JSON, et le front-end décide quoi afficher ». Au lieu de cela, Inertia propose une troisième voie : vous écrivez vos contrôleurs en PHP comme d'habitude, mais au lieu de retourner un template Blade ou une réponse JSON, vous retournez une réponse Inertia avec les données et le nom du composant. Inertia côté client (JavaScript) intercepte cette réponse, trouve le composant approprié (React/Vue) et le rend en injectant les données reçues. La navigation entre les pages se fait sans rechargement complet, comme dans une SPA, mais tout le routage et la logique métier restent côté serveur.

Pourquoi en avez-vous besoin ? Premièrement, cela simplifie considérablement l'architecture : vous n'avez pas à maintenir deux applications distinctes (backend API et front-end SPA) avec une duplication de la logique d'authentification et de validation. Deuxièmement, cela conserve tous les avantages de Laravel (ORM Eloquent, composants Blade pour les e-mails, Artisan, middleware) et tous les avantages de React/Vue (réactivité, approche par composants, vaste écosystème). Troisièmement, cela offre une excellente expérience développeur (DX) : vous travaillez dans un seul dépôt, utilisez un seul routeur (Laravel), et Inertia gère de manière transparente l'état de l'application côté client.

2. Installation

L'installation se compose de deux parties : côté serveur (PHP) et côté client (JavaScript). Il est supposé que vous avez déjà installé Laravel (version 8, 9, 10 ou 11).

Étape 1 : Installation du package serveur (PHP)

Exécutez dans le terminal à la racine de votre projet Laravel :

composer require inertiajs/inertia-laravel

Étape 2 : Installation de l'adaptateur client (JavaScript)

Choisissez votre framework front-end et exécutez la commande correspondante :

Pour React :

npm install @inertiajs/react react react-dom

Pour Vue 3 :

npm install @inertiajs/vue3 vue

Pour Svelte :

npm install @inertiajs/svelte svelte

Étape 3 : Publication de la configuration (optionnelle)

php artisan vendor:publish --provider="Inertia\ServiceProvider"

Étape 4 : Configuration du template racine

Créez le fichier resources/views/app.blade.php avec le contenu suivant :

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>@yield('title', config('app.name'))</title>
    @viteReactRefresh
    @vite(['resources/js/app.jsx'])
    @inertiaHead
</head>
<body>
    @inertia
</body>
</html>

La directive @inertia est l'endroit où Inertia insérera votre application. @inertiaHead permet de gérer les balises d'en-tête depuis les composants.

Étape 5 : Configuration de Vite (si vous utilisez Vite)

Dans le fichier vite.config.js, ajoutez le plugin pour React ou Vue :

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import react from '@vitejs/plugin-react'; // ou @vitejs/plugin-vue

export default defineConfig({
    plugins: [
        laravel({
            input: 'resources/