InertiaJs: cos'è e come integrarlo in un'applicazione Laravel

Nel mondo dello sviluppo web moderno, le Single Page Applications (SPA) sono diventate sempre più popolari grazie alla loro capacità di creare esperienze utente fluide e reattive. Le SPA consentono agli utenti di navigare all'interno di un'applicazione web senza dover ricaricare l'intera pagina ogni volta che desiderano visualizzare un nuovo contenuto o eseguire un'azione. Questo approccio offre un'esperienza simile a quelle delle applicazioni desktop e ha trasformato radicalmente il modo in cui interagiamo con il web.

Tuttavia lo sviluppo di SPA può comportare alcune sfide, compresa la gestione complessa delle API REST, la SEO e l'integrazione con framework backend come Laravel. È qui che Inertia.js si pone come una soluzione innovativa per semplificare lo sviluppo di SPA e superare queste sfide in modo elegante e efficiente. In questo articolo, vedremo cosa è Inertia.js e come integrarlo in un progetto Laravel.

Che cos'è Inertia.js

Come possiamo leggere nella documentazione ufficiale:

Inertia non è un framework, né è un sostituto per i tuoi framework esistenti lato server o lato client. Piuttosto, è progettato per lavorare con essi. Pensalo come una colla che li connette.

Inertia sfrutta il concetto di rendering lato server per migliorare l'esperienza di sviluppo. Quando un utente accede ad una pagina web inertia, il server restituisce l'HTML completo, insieme ai dati necessari per il rendering del frontend. In seguito, Inertia gestisce le interazioni lato client, consentendo di aggiornare solo le parti della pagina che cambiano, senza dover ricaricare l'intera pagina.

Ecco come funziona schematicamente il flusso di lavoro di Inertia.js

Il server restituisce una pagina HTML con dati iniziali incorporati nel payload.
Il frontend, che può essere sviluppato con React, Vue.js o Svelte, utilizza questi dati iniziali per renderizzare la pagina.
Quando si verifica un'interazione utente, ad esempio un click su di un link o viene inviato un modulo, Inertia.js effettua una richiesta al server senza ricaricare l'intera pagina. Il server elabora la richiesta e restituisce solo i dati e la vista necessari per aggiornare la parte interessata della pagina.
Il frontend utilizza i nuovi dati e la vista ricevuti dal server per aggiornare la pagina in modo reattivo, tutto senza la necessità di ricaricare la pagina.

Come integrare Inertia in un progetto laravel

Vediamo ora come integrare Inertia all'interno di un progetto laravel. Nel nostro caso andremo ad utilizzare React per il frontend.
Iniziamo creando un progetto laravel ex-novo

laravel new Inertia

spostiamoci nella cartella del progetto e installiamo l'adattatore lato server utilizzando composer

composer require inertiajs/inertia-laravel

Ora dobbiamo creare un nuovo file all'interno di resources/views chiamato app.blade.php il cui contenuto sarà il nostro template root

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">

        <title inertia>{{ config('app.name', 'Laravel') }}</title>

        <!-- Scripts -->
        @viteReactRefresh
        @vite(['resources/js/app.jsx', 'resources/css/app.css'])
        @inertiaHead
    </head>
    <body>
        @inertia
    </body>
</html>

Impostiamo il middleware di Inertia lanciando da terminale il comando

php artisan inertia:middleware

e andando a registrarlo nel file kenrnel.php all'interno di app/Http

'web' => [
     ...
    \App\Http\Middleware\HandleInertiaRequests::class,
],

Fatto questo possiamo passare al lato client. Installiamo l'adattatore per il framework che intendiamo utilizzare, come detto nel nostro caso si tratta di React

npm install @inertiajs/react

installiamo anche altre dipendenze che ci servono

npm i @vitejs/plugin-react react react-dom

modifichiamo il file vite.config.js in questo modo

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

export default defineConfig({
    plugins: [
        react(),
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.jsx'],
            refresh: true,
        }),
    ],
});

rinominiamo il file app.js in app.jsx e sostituiamo il suo contenuto con il seguente codice

import { createInertiaApp } from "@inertiajs/react";
import { createRoot } from "react-dom/client";

createInertiaApp({
    resolve: (name) => {
        const pages = import.meta.glob("./Pages/**/*.jsx", { eager: true });
        return pages[`./Pages/${name}.jsx`];
    },
    setup({ el, App, props }) {
        createRoot(el).render(<App {...props} />);
    },
});

creiamo una cartella Pages all'interno di resources/js e creiamo un componente di prova

export default function Dashboard() {
    return <div>Dashboard</div>;
}

impostiamo la nuova rotta in web.php utilizzando la funzione render di Inertia

<?php

use Illuminate\Support\Facades\Route;
use Inertia\Inertia;

Route::get('/', function () {
    return Inertia::render('Dashboard');
});

A questo punto possiamo lanciare il server locale e controllare che tutto funzioni.

Ora che abbiamo visto come aggiungere Inertia ad un progetto Laravel vediamo una breve panoramica di alcuni "strumenti" che Inertia ci offre per la gestione delle nostre SPA

Head

Head è un componente che Inertia ci mette a disposizione per gestire i meta data della nostra pagina. Il suo utilizzo è molto semplice: basta richiamare il componente dopo averlo importato e inserire al suo interno i tag che ci interessano

import { Head } from '@inertiajs/react';

export default function Users() {
    
    return (
        <Head>
            <title>Lista Utenti</title>
            <meta
                name="description"
                content="In questa pagina è possibile visualizzare la lista degli utenti registrati"
            />
        </Head>
    );
}

Form Helper

Per la gestione dei form Inertia ci mette a disposizione un helper (useForm) il cui utilizzo risulta relativamente semplice. Quando inizializziamo il form utilizzando useForm, possiamo fornire un oggetto con i campi del form e i relativi valori iniziali. Ad esempio

const { data, setData, post, processing, errors } = useForm({
    username: '',
    email: '',
    password: '',
});

'data': Questo oggetto contiene i valori dei campi del form. È un oggetto reattivo, il che significa che qualsiasi modifica ai valori del form verrà immediatamente riflessa nell'interfaccia utente.
'setData': Questa funzione consente di aggiornare i valori dei campi del form in modo reattivo.
'post': È una funzione che gestisce l'invio dei dati del form al server. Questa funzione accetta il percorso al quale inviare i dati come argomento. È presente una funzione per ogni metodo HTTP, abbiamo quindi GET, POST, PUT, PATCH, DELETE.
'processing': Si tratta di un valore booleano che indica se il form è attualmente in elaborazione. Questo è utile per disabilitare bottoni di invio e prevenire l'invio multiplo o per mostrare feedback all'utente.
'errors': È un oggetto che contiene gli errori di validazione restituiti dal server. Questi errori possono essere associati ai campi del form e visualizzati all'utente in modo appropriato.

Componente Link

Il componente Link è una parte chiave dell'ecosistema Inertia ed è utilizzato per gestire le transizioni tra le pagine senza dover ricaricare completamente la pagina. Come possiamo leggere nella documentazione

Questo componente è un semplice involucro attorno a un link standard <a> che intercetta gli eventi di click e impedisce il ricaricamento completo della pagina. Questo è il modo in cui Inertia fornisce un'esperienza di applicazione a singola pagina una volta che la tua applicazione è stata caricata.

Anche in questo caso l'utilizzo è molto semplice andando, in pratica, a sostituire il tag anchor

import { Link } from '@inertia/react';

function Header() {
    return (
        <div>
            <nav>
                <ul>
                    <li>
                        <Link href="/">Home</Link>
                    </li>
                    <li>
                        <Link href="/about">About</Link>
                    </li>
                    <li>
                        <Link href="/contact">Contact</Link>
                    </li>
                </ul>
            </nav>
        </div>
    );
}

Shared Data

In Inertia con Shared Data ci si riferisce a dati o variabili che possono essere resi disponibili in tutte le viste dell'applicazione senza doverli passare manualmente da una vista all'altra. In altre parole, è possibile condividere dati tra le diverse componenti o pagine dell'applicazione in modo trasparente.

È possibile utilizzare gli Shared Data utilizzando il metodo share fornito da Inertia all'interno di un controller in modo da rendere disponibile tale dato all'interno di tutte le viste associate al controller.

 public function index()
{
    // Recupera il nome dell'utente autenticato
    $user = Auth::user();
    $userName = $user->name;

    // Condividi il nome dell'utente con Inertia.js
    Inertia::share('userName', $userName);

    // Restituisci la vista
    return Inertia::render('Dashboard');
}

Possiamo recuperare il dato all'interno della vista in questo modo

import { usePage } from '@inertiajs/react'

export default function Layout({ children }) {
  const { userName } = usePage().props

  return (
    <main>
      <header>
        You are logged in as: {userName}
      </header>
      <content>
        {children}
      </content>
    </main>
  )
}

Conclusioni

In questo articolo abbiamo visto brevemente cosa è Inertia e come integrarlo in laravel senza utilizzare uno starter kit. La combinazione di Laravel e Inertia.js offre un ambiente di sviluppo potente e flessibile che semplifica notevolmente la creazione di SPA reattive e performanti. In definitiva, Inertia è una risorsa preziosa per gli sviluppatori che desiderano semplificare il processo di sviluppo di SPA che vi invito ad approfondire in quanto ritengo che sia un'aggiunta significativa al toolkit di sviluppo web moderno.