Inertia.js for PHP: Complete Guide with Examples

\n\n

1. What It Is and Why You Need It

\n\n

Inertia.js is not a framework or a library for creating SPA (Single Page Application) in the classical sense. It is rather a "bridge" or "adapter" that allows you to create modern single-page applications using a classic server-side framework (in our case Laravel on PHP) and any modern frontend framework (React, Vue.js or Svelte) without the need to write a separate REST API.

\n\n

The main problem that Inertia.js solves is abandoning the traditional approach of "server renders HTML" or "server returns JSON, and the frontend decides what to render." Instead, Inertia offers a third path: you write controllers in PHP as usual, but instead of returning a Blade template or JSON response, you return an Inertia response with data and a component name. Inertia on the client (JavaScript) intercepts this response, finds the required component (React/Vue) and renders it, substituting the received data. Navigation between pages occurs without a full page reload, like in SPA, but all routing and business logic remain on the server.

\n\n

Why is this needed? Firstly, it dramatically simplifies the architecture: you don't need to maintain two separate applications (backend API and frontend SPA) with duplicated authorization and validation logic. Secondly, it preserves all the advantages of Laravel (ORM Eloquent, Blade components for emails, Artisan, middleware) and all the advantages of React/Vue (reactivity, component approach, huge ecosystem). Thirdly, it provides an excellent Developer Experience (DX): you work in one repository, use one router (Laravel), and Inertia transparently manages the application state on the client.

\n\n

2. Installation

\n\n

Installation consists of two parts: server-side (PHP) and client-side (JavaScript). It is assumed that you already have Laravel installed (version 8, 9, 10 or 11).

\n\n

Step 1: Install the server package (PHP)

\n

Run in the terminal in the root of your Laravel project:

\n

composer require inertiajs/inertia-laravel

\n\n

Step 2: Install the client adapter (JavaScript)

\n

Choose your frontend framework and run the corresponding command:

\n\n

For React:

\n

npm install @inertiajs/react react react-dom

\n\n

For Vue 3:

\n

npm install @inertiajs/vue3 vue

\n\n

For Svelte:

\n

npm install @inertiajs/svelte svelte

\n\n

Step 3: Publish configuration (optional)

\n

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

\n\n

Step 4: Set up the root template

\n

Create a file resources/views/app.blade.php with the following content:

\n

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

\n

The @inertia directive is the place where Inertia will insert your application. @inertiaHead is for managing headers from components.

\n\n

Step 5: Configure Vite (if using Vite)

\n

In the vite.config.js file, add the plugin for React or Vue:

\n

import { defineConfig } from 'vite';\nimport laravel from 'laravel-vite-plugin';\nimport react from '@vitejs/plugin-react'; // or @vitejs/plugin-vue\n\nexport default defineConfig({\n