Inertia.js para PHP: guía completa con ejemplos prácticos

1. ¿Qué es Inertia.js y por qué usarlo?

Inertia.js no es un framework ni una librería para crear SPA (Single Page Application) en el sentido clásico. Es más bien un "puente" o "adaptador" que te permite construir aplicaciones modernas de una sola página usando un framework de servidor tradicional (en nuestro caso, Laravel con PHP) y cualquier framework frontend moderno (React, Vue.js o Svelte) sin necesidad de escribir una API REST separada.

El principal problema que resuelve Inertia.js es eliminar el enfoque tradicional de "el servidor renderiza HTML" o "el servidor devuelve JSON y el frontend decide qué mostrar". En su lugar, Inertia propone un tercer camino: escribes tus controladores en PHP como siempre, pero en lugar de devolver una plantilla Blade o una respuesta JSON, devuelves una respuesta Inertia con los datos y el nombre del componente. Inertia en el cliente (JavaScript) intercepta esta respuesta, encuentra el componente adecuado (React/Vue) y lo renderiza con los datos recibidos. La navegación entre páginas ocurre sin recarga completa, como en una SPA, pero todo el enrutamiento y la lógica de negocio permanecen en el servidor.

¿Por qué es útil? Primero, simplifica drásticamente la arquitectura: no necesitas mantener dos aplicaciones separadas (backend API y frontend SPA) duplicando lógica de autenticación y validación. Segundo, conserva todas las ventajas de Laravel (ORM Eloquent, componentes Blade para correos, Artisan, middleware) y todas las ventajas de React/Vue (reactividad, enfoque basado en componentes, ecosistema enorme). Tercero, ofrece una excelente experiencia de desarrollo (DX): trabajas en un solo repositorio, usas un solo enrutador (Laravel), e Inertia gestiona de forma transparente el estado de la aplicación en el cliente.

2. Instalación

La instalación consta de dos partes: servidor (PHP) y cliente (JavaScript). Se asume que ya tienes Laravel instalado (versión 8, 9, 10 u 11).

Paso 1: Instalar el paquete del servidor (PHP)

Ejecuta en la terminal, en la raíz de tu proyecto Laravel:

composer require inertiajs/inertia-laravel

Paso 2: Instalar el adaptador del cliente (JavaScript)

Elige tu framework frontend y ejecuta el comando correspondiente:

Para React:

npm install @inertiajs/react react react-dom

Para Vue 3:

npm install @inertiajs/vue3 vue

Para Svelte:

npm install @inertiajs/svelte svelte

Paso 3: Publicar la configuración (opcional)

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

Paso 4: Configurar la plantilla raíz

Crea el archivo resources/views/app.blade.php con el siguiente contenido:

<!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 directiva @inertia es el lugar donde Inertia insertará tu aplicación. @inertiaHead permite gestionar los encabezados desde los componentes.

Paso 5: Configurar Vite (si usas Vite)

En el archivo vite.config.js, agrega el plugin para React o Vue:

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

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