Inertia.js para PHP: guia completo com exemplos práticos

1. O que é e para que serve

Inertia.js não é um framework nem uma biblioteca para criar SPAs (Single Page Applications) no sentido clássico. É mais uma "ponte" ou "adaptador" que permite criar aplicações modernas de página única usando um framework server-side tradicional (no nosso caso, Laravel com PHP) e qualquer framework front-end moderno (React, Vue.js ou Svelte) sem a necessidade de escrever uma API REST separada.

O principal problema que o Inertia.js resolve é eliminar a abordagem tradicional de "servidor renderiza HTML" ou "servidor retorna JSON e o front-end decide o que desenhar". Em vez disso, o Inertia oferece um terceiro caminho: você escreve os controllers em PHP como de costume, mas em vez de retornar um template Blade ou uma resposta JSON, você retorna uma resposta Inertia com os dados e o nome do componente. O Inertia no cliente (JavaScript) intercepta essa resposta, encontra o componente correto (React/Vue) e o renderiza, injetando os dados recebidos. A navegação entre páginas acontece sem recarregamento completo, como em um SPA, mas todo o roteamento e a lógica de negócios permanecem no servidor.

Por que usar isso? Primeiro, simplifica drasticamente a arquitetura: você não precisa manter duas aplicações separadas (backend API e frontend SPA) com lógica de autenticação e validação duplicada. Segundo, mantém todas as vantagens do Laravel (ORM Eloquent, componentes Blade para e-mails, Artisan, middleware) e todas as vantagens do React/Vue (reatividade, abordagem de componentes, ecossistema enorme). Terceiro, proporciona uma excelente Experiência do Desenvolvedor (DX): você trabalha em um único repositório, usa um único roteador (Laravel), e o Inertia gerencia de forma transparente o estado da aplicação no cliente.

2. Instalação

A instalação tem duas partes: servidor (PHP) e cliente (JavaScript). Presume-se que você já tenha o Laravel instalado (versão 8, 9, 10 ou 11).

Passo 1: Instalação do pacote servidor (PHP)

Execute no terminal na raiz do seu projeto Laravel:

composer require inertiajs/inertia-laravel

Passo 2: Instalação do adaptador cliente (JavaScript)

Escolha seu framework front-end e execute o comando correspondente:

Para React:

npm install @inertiajs/react react react-dom

Para Vue 3:

npm install @inertiajs/vue3 vue

Para Svelte:

npm install @inertiajs/svelte svelte

Passo 3: Publicar configuração (opcional)

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

Passo 4: Configurar o template raiz

Crie o arquivo resources/views/app.blade.php com o seguinte conteúdo:

<!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>

A diretiva @inertia é o local onde o Inertia irá inserir sua aplicação. @inertiaHead serve para gerenciar os títulos a partir dos componentes.

Passo 5: Configurar o Vite (se estiver usando Vite)

No arquivo vite.config.js, adicione o plugin para 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/