Laravel Maestro — l'orchestratore per lo sviluppo degli starter kit

Analisi del nuovo repository ufficiale di Laravel, Maestro. Spiega il meccanismo dell’orchestratore che gestisce più varianti di starter kit in un unico monorepo per rendere efficienti i contributi.

Questo articolo si basa su un’indagine del codice sorgente. Non esiste ancora una documentazione ufficiale e il repository è precedente al rilascio ufficiale (dato di aprile 2026).

​

Cos’è Maestro

Laravel Maestro è un orchestratore monorepo che centralizza la gestione degli starter kit di Laravel.

Gli starter kit di Laravel hanno più stack — React, Vue, Svelte (Inertia) e Livewire — e per ciascuno esistono oltre 15 varianti combinando modalità di autenticazione (Fortify, WorkOS) e opzioni (Teams, Blank). Maestro gestisce tutte queste varianti in un unico repository e fornisce un meccanismo che riflette automaticamente le modifiche nei singoli repository degli starter kit.

​

Quale problema risolve

Quando gli starter kit sono suddivisi in molte varianti, riportare una singola modifica in tutte diventa complesso. Ad esempio, aprire PR separate per correggere la validazione di un form di autenticazione in React, Vue, Svelte e Livewire è inefficiente.

Maestro risolve questo problema con una “struttura gerarchica di layer condivisi e layer di variante”. L’orchestratore decide a quale layer applicare la modifica e la propaga automaticamente nel punto più appropriato.

​

Varianti degli starter kit

Gli starter kit gestiti da Maestro sono composti da due stack.

​

Stack Livewire (6 varianti)

Variante	Descrizione
Blank	Configurazione minima senza autenticazione
Fortify	Autenticazione con Laravel Fortify
Fortify (Multi-file Components)	Configurazione con view Blade separate in file di componente
Fortify (Teams)	Autenticazione Fortify + supporto ai Team
WorkOS	Autenticazione con WorkOS
WorkOS (Teams)	Autenticazione WorkOS + supporto ai Team

​

Stack Inertia (15 varianti)

Con la combinazione dei tre framework React, Vue e Svelte × Blank, Fortify, WorkOS × presenza/assenza di Team, si arriva a un totale di 15 varianti.

​

Struttura del repository

laravel/maestro/
├── orchestrator/    # App Laravel che gestisce la build
│   ├── app/Console/Commands/BuildCommand.php
│   ├── app/Enums/StarterKit.php
│   └── scripts/
├── kits/            # File sorgente degli starter kit
│   ├── Shared/      # File comuni a tutte le varianti
│   ├── Livewire/    # File specifici Livewire
│   └── Inertia/     # File specifici Inertia (React/Vue/Svelte)
└── browser_tests/   # Test browser
    ├── bootstrap/
    ├── common/
    └── teams/

La directory orchestrator stessa è un’applicazione Laravel e gestisce la build e l’esecuzione degli starter kit.

​

Sistema di gerarchia dei file

Il cuore di Maestro è il meccanismo che “compone lo starter kit sovrapponendo layer”. Nel caso di Livewire (Fortify), i file vengono copiati nell’ordine seguente e i layer successivi sovrascrivono quelli precedenti.

Grazie a questa gerarchia esiste una regola chiara: “le modifiche comuni a tutti i kit vanno in Shared/, quelle specifiche di Livewire in Livewire/”.

​

Flusso di contribuzione

I contributi agli starter kit si effettuano nel repository Maestro, non nei singoli repository degli starter kit.

1. Spostati nella directory orchestrator e builda il kit

   cd orchestrator
   php artisan build
   

   Un prompt interattivo permette di selezionare il kit di destinazione e la variante di autenticazione. Puoi anche specificarli direttamente con dei flag.

   php artisan build --kit=vue
   php artisan build --kit=react --workos
   php artisan build --kit=livewire --teams
   php artisan build --kit=vue --workos --teams
   
2. Avvia il kit buildato

   composer kit:run
   

   Il server di sviluppo di Laravel e il file watcher vengono avviati contemporaneamente. Le modifiche fatte in build/ vengono copiate automaticamente nella posizione corretta in kits/.

3. Modifica e testa

   Modifica i file nella directory build/. Il watcher rileva le modifiche e le riflette automaticamente nella directory kits/.

4. Crea una PR

   Effettua il commit delle modifiche in kits/ e apri una PR. Una volta mergiata, Maestro fa il push automaticamente delle modifiche nei singoli repository degli starter kit.

La directory build/ è gitignorata. Fai tutte le modifiche in build/ e commit solo dopo che il watcher ha sincronizzato con kits/.

​

Altri comandi di sviluppo

​

Lint

# Esegui Pint su kits e browser_tests (solo PHP)
composer kits:pint

# Lint PHP + lint frontend per ogni variante Inertia
composer kits:lint

# Solo per un framework specifico
composer kits:lint -- --vue
composer kits:lint -- --react --svelte

​

Test browser

# Esegui i test browser per tutte le varianti
composer kits:browser-tests

# Restringi a framework o variante
composer kits:browser-tests -- --vue
composer kits:browser-tests -- --livewire --fortify

I test browser girano con Pest + Playwright. Nella directory browser_tests/ i test sono organizzati in tre livelli: bootstrap/ (configurazione comune), common/ (per Fortify) e teams/ (per Teams).

​

Restringere con i flag

Ogni comando può combinare i flag --livewire, --react, --svelte, --vue con --blank, --fortify, --workos, --teams per restringere il target.

# Solo le varianti Fortify di Vue e Svelte
composer kits:check -- --vue --svelte --fortify

# Solo le varianti WorkOS di tutti i framework
composer kits:check -- --workos

​

Configurazione delle variabili d’ambiente per WorkOS

Se builda ed esegui varianti WorkOS, configura Client ID e API Key di WorkOS in orchestrator/.env. Al momento della build questi valori vengono copiati nel file .env della directory build/.

# orchestrator/.env
WORKOS_CLIENT_ID=your_client_id
WORKOS_API_KEY=your_api_key

​

Stato attuale dello sviluppo

• Repository GitHub: laravel/maestro
• Rilascio ufficiale: nessuno (tag di versione e release non pubblicati)
• Ultimo commit: aprile 2026 (sviluppo attivo)
• Versione PHP richiesta: ^8.2
• Versione Laravel: ^13.0

Maestro non è un pacchetto per l’utente finale, ma funziona come infrastruttura di sviluppo per il team di Laravel e i contributor. Gli starter kit veri e propri (come laravel/starter-kit-react) sono generati e gestiti a partire da questo monorepo tramite Maestro.

Repository laravel/maestro

Se sei interessato a contribuire agli starter kit, inizia leggendo il README di Maestro.

Documentazione ufficiale degli starter kit Laravel

Per l’uso degli starter kit consulta la documentazione ufficiale.