React con Laravel API: full-stack architecture per applicazioni gestionali moderne

La combinazione React + Laravel API è l'architettura full-stack che uso quando un cliente ha due requisiti simultanei: un backend PHP che funziona (e che non ha senso riscrivere) e un frontend che deve offrire un'esperienza utente di livello applicativo - tabelle con sorting e filtering in-memory, form multi-step con validazione interattiva, drag-and-drop per il riordinamento, aggiornamenti real-time senza refresh, e transizioni animate tra le sezioni. In questi casi, né Blade (troppo limitato per l'interattività richiesta) né Livewire (che richiede un round-trip al server per ogni interazione) né Inertia.js (che elimina il layer API ma lega il frontend al ciclo request-response di Laravel) sono la scelta giusta. Serve un frontend JavaScript separato con il proprio state management, il proprio routing client-side e la propria pipeline di build - e React è il framework che scelgo quando il progetto ha requisiti di interattività che superano la soglia del server-rendered.

Ho costruito quattro applicazioni gestionali con questa architettura negli ultimi due anni per clienti del settore servizi e distribuzione. In tutti i casi, il backend Laravel preesisteva con la sua logica di business, le sue regole di validazione e il suo database - il lavoro è stato esporre un'API REST documentata (con le tecniche descritte nel mio articolo su OpenAPI per Laravel) e costruire un frontend React che la consumasse. Il risultato è un'architettura dove il backend PHP è responsabile della logica di business, della persistenza e della sicurezza, e il frontend React è responsabile dell'esperienza utente - due codebase separate con responsabilità chiare e deployment indipendente.

Quando React + API è la scelta giusta e quando è over-engineering?

Questa architettura ha un costo strutturale che va compreso prima di adottarla: due repository, due pipeline di build, due deployment, due set di competenze nel team, e un layer di comunicazione HTTP tra frontend e backend che introduce latenza, complessità di autenticazione e surface area di errore. Per la maggior parte dei gestionali PMI con 10-50 utenti interni e requisiti di interattività standard (CRUD, tabelle, form), questo costo non è giustificato - Livewire o Inertia producono lo stesso risultato con un terzo della complessità architetturale.

React + API diventa la scelta giusta in tre scenari specifici. Il primo è quando l'interfaccia ha requisiti di interattività elevati che richiedono state management client-side sofisticato: un configuratore di prodotto con preview real-time, un editor di documenti con collaborazione simultanea, una dashboard con drag-and-drop di widget, o un'applicazione con offline capability che deve funzionare senza connessione al server. Il secondo scenario è quando lo stesso backend serve più frontend: un'app web React, un'app mobile React Native e un portale partner Vue.js - tre client che consumano la stessa API. Il terzo è quando il team ha competenze frontend forti e vuole pieno controllo sull'architettura client-side.

Nel mio profilo professionale trovi il dettaglio dell'esperienza multi-stack che porto in queste decisioni architetturali - la scelta tra React+API, Inertia e Livewire è la decisione più impattante sulla sostenibilità a lungo termine del progetto, e va presa con dati, non con preferenze.

Autenticazione con Sanctum SPA: il pattern che funziona

L'autenticazione tra un frontend React (servito da un dominio o una porta diversa dal backend) e un'API Laravel è il punto dove la maggior parte dei tutorial fallisce, perché la configurazione coinvolge CORS, cookie cross-domain, CSRF protection e Sanctum in un intreccio che, se sbagliato in un solo punto, produce errori 401 o 419 apparentemente casuali.

Il pattern che uso è Laravel Sanctum in modalità SPA - non token Bearer nel localStorage (un antipattern di sicurezza), ma cookie httpOnly impostato dal server dopo un login standard. Il flusso è: il frontend React chiama POST /sanctum/csrf-cookie per ottenere il token CSRF, poi chiama POST /login con le credenziali, e da quel momento tutte le richieste successive includono automaticamente il cookie di sessione (con credentials: 'include' nel fetch). Il cookie è httpOnly (non accessibile da JavaScript, immune a XSS), SameSite=Lax (protetto da CSRF), e Secure (trasmesso solo su HTTPS).

La configurazione richiede tre passaggi nel backend Laravel: impostare SANCTUM_STATEFUL_DOMAINS nel .env con il dominio del frontend (es. app.gestionale.it), configurare SESSION_DOMAIN con il dominio comune (es. .gestionale.it per condividere il cookie tra api.gestionale.it e app.gestionale.it), e abilitare CORS con supports_credentials: true nel file config/cors.php. Nel frontend React, la configurazione è una riga nel client HTTP (Axios o fetch): withCredentials: true per includere i cookie in ogni richiesta cross-origin.

React Query per lo stato server: eliminare il boilerplate di fetch

Il secondo componente architetturale che ha standardizzato il mio workflow è TanStack Query (precedentemente React Query) per la gestione dello stato server - i dati che provengono dall'API e che devono essere cachati, invalidati, aggiornati e sincronizzati tra i componenti. Senza React Query, ogni componente che ha bisogno di dati dall'API implementa il proprio ciclo useEffect → fetch → setState → loading state → error handling - un boilerplate di 20-30 righe per ogni endpoint consumato, duplicato in ogni componente che accede agli stessi dati, senza caching condiviso e senza invalidazione automatica.

Con React Query, il fetch viene dichiarato con useQuery e il framework gestisce tutto il resto: caching automatico (se due componenti chiedono gli stessi dati, il fetch avviene una sola volta), refetch in background quando la finestra riprende il focus, invalidazione esplicita dopo una mutation (quando crei un ordine, la lista degli ordini viene rinfrescata automaticamente), retry automatico su errori di rete, e indicatori di loading/error/success come valori derivati.

Il beneficio pratico nel gestionale più recente che ho costruito è stato la riduzione del codice di data fetching da circa 1.200 righe (con useEffect + useState manuali) a circa 350 righe (con useQuery + useMutation) - una riduzione del 70% nel boilerplate, con un comportamento più robusto (retry automatico, caching) e una user experience migliore (dati che appaiono istantaneamente dalla cache mentre il refetch avviene in background).

Struttura del progetto React: la convenzione che uso per i gestionali

In ogni gestionale React che costruisco, la struttura del progetto segue una convenzione che ho stabilizzato dopo quattro progetti e che bilancia la semplicità iniziale con la scalabilità futura. La cartella src/ è organizzata per feature, non per tipo di file: ogni sezione del gestionale (ordini, clienti, fatture, magazzino) ha la propria cartella che contiene componenti, hook, tipi TypeScript e query React Query - tutto ciò che riguarda quella feature è nello stesso posto, non distribuito tra components/, hooks/, types/ e queries/.

Questa organizzazione per feature ha un vantaggio pratico enorme quando il team cresce: uno sviluppatore che lavora sulla sezione ordini modifica file solo nella cartella features/ordini/, senza rischio di conflitti con chi lavora sulla sezione fatture. E quando una feature viene rimossa o ristrutturata, tutto il suo codice è in un posto - non serve cercare componenti, hook e tipi sparsi in 8 cartelle diverse.

Il secondo pattern architetturale che applico è la separazione tra componenti di presentazione e componenti container. I componenti di presentazione ricevono dati via props e producono JSX - non sanno da dove vengono i dati e non fanno fetch. I componenti container usano React Query per caricare i dati e li passano ai componenti di presentazione. Questa separazione rende i componenti di presentazione riutilizzabili (la stessa OrderTable può mostrare ordini da fonti diverse), testabili (puoi testare la presentazione passando dati mock senza mockare l'API), e comprensibili (leggendo il componente container capisci quali dati servono, leggendo il componente di presentazione capisci come vengono mostrati).

Il terzo pattern è l'uso esclusivo di TypeScript con strict mode - non JavaScript. Per un gestionale che gestisce dati di business (importi, date, codici fiscali, stati degli ordini), la tipizzazione statica cattura errori che in JavaScript passerebbero silenziosamente: un importo trattato come stringa invece che come numero, uno stato dell'ordine con un valore non previsto, un campo nullable acceduto senza null check. TypeScript in strict mode aggiunge un costo di sviluppo iniziale (dichiarare i tipi), ma riduce drasticamente il tempo di debugging in produzione - un rapporto costo/beneficio che ho verificato empiricamente: i quattro gestionali TypeScript che ho costruito hanno il 60% in meno di bug in produzione rispetto ai progetti precedenti senza tipizzazione.

Performance: lazy loading, code splitting e prefetching intelligente

Un gestionale React con 30-50 pagine e una libreria di componenti ricca (tabelle, form, grafici, mappe) produce un bundle JavaScript che può superare il megabyte. Servire 1,2 MB di JavaScript ad ogni caricamento - la maggior parte del quale non serve per la pagina corrente - peggiora il tempo di caricamento iniziale e consuma banda inutilmente, specialmente per gli utenti che accedono da reti mobili o da sedi aziendali con connettività limitata.

La soluzione è il code splitting con React.lazy() e Suspense: ogni pagina del gestionale viene importata dinamicamente e il suo codice viene scaricato solo quando l'utente naviga a quella pagina. Il bundle iniziale contiene solo il layout dell'applicazione, la navigazione e i componenti condivisi (circa 200 KB) - tutto il resto viene caricato on-demand. In pratica, l'utente che apre la dashboard scarica 200 KB di JavaScript iniziale e 50 KB per i widget della dashboard; quando naviga agli ordini, scarica altri 80 KB per la pagina ordini. Il tempo di caricamento percepito è significativamente migliore perché l'utente vede la dashboard in 800 ms invece di aspettare 2,5 secondi per il download del bundle completo.

Il prefetching intelligente è il complemento del code splitting: quando l'utente passa il mouse sopra un link di navigazione, React Router inizia a scaricare il bundle della pagina di destinazione in background - così che quando l'utente clicca, la pagina è già pronta e la navigazione sembra istantanea. Questo pattern produce una user experience che rivaleggia con le applicazioni desktop: nessun spinner di caricamento tra le pagine, nessun ritardo percettibile, nessun momento in cui l'utente vede una pagina bianca.

Deployment: Vite, Nginx e la separazione dei percorsi

Il deployment dell'architettura React + Laravel richiede la configurazione di Nginx per servire il frontend e il backend dallo stesso dominio o da sottodomini correlati. Il pattern che uso è app.gestionale.it per il frontend React e api.gestionale.it per il backend Laravel - due sottodomini che condividono il dominio di secondo livello per la condivisione dei cookie Sanctum.

Il frontend React viene buildato con Vite (npm run build) e deployato come file statici su Nginx - HTML, CSS e JavaScript pre-compilati che non richiedono un runtime server-side. Nginx serve questi file direttamente dalla cartella dist/ con un fallback a index.html per il routing client-side di React Router (senza il fallback, un refresh su /ordini/42 restituirebbe un 404 perché Nginx cercherebbe un file /ordini/42/index.html che non esiste).

Il backend Laravel viene deployato normalmente su PHP-FPM con la configurazione standard di Nginx per le applicazioni PHP. Le due configurazioni Nginx sono indipendenti - il frontend può essere aggiornato senza toccare il backend e viceversa, abilitando il deployment indipendente che è uno dei vantaggi principali di questa architettura.

Il costo del deployment separato è la gestione di due pipeline CI/CD - una per il backend (test PHPUnit, lint, deploy PHP) e una per il frontend (test Jest/Vitest, lint ESLint, build Vite, deploy file statici). Per i team piccoli (3-5 sviluppatori) dove le stesse persone lavorano su entrambi i layer, ho configurato una pipeline unica in GitHub Actions che esegue entrambe le build in parallelo e deploya entrambi i componenti in sequenza - il backend prima (per garantire che le API nuove siano disponibili quando il frontend le chiama) e il frontend subito dopo.

L'architettura React + Laravel API non è per tutti - ma quando i requisiti la giustificano, è l'approccio che produce l'esperienza utente migliore combinata con la solidità del backend Laravel. La chiave è non adottarla per default quando Livewire o Inertia sarebbero sufficienti, e non evitarla per paura della complessità quando l'interattività richiesta la rende necessaria. Se stai valutando quale architettura frontend adottare per il tuo gestionale Laravel, contattami per una valutazione: in una sessione di due ore analizziamo i requisiti di interattività, valutiamo il rapporto complessità/beneficio di ogni opzione, e scegliamo l'architettura che bilancia esperienza utente e sostenibilità per il tuo team.