> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  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).
</Info>

## Cos'è Maestro

[Laravel Maestro](https://github.com/laravel/maestro) è un orchestratore monorepo che centralizza la gestione degli [starter kit](https://laravel.com/starter-kits) 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.

```mermaid theme={null}
graph TD
    A["laravel/maestro<br>(monorepo)"] --> B["orchestrator/<br>build tool"]
    A --> C["kits/<br>file sorgente"]
    A --> D["browser_tests/<br>test browser"]
    B --> E["Con il comando build<br>compone le varianti"]
    E --> F["build/<br>kit compilati"]
    F --> G["composer kit:run<br>per avvio e watch"]
    G --> H["Le modifiche vengono<br>riflesse automaticamente in kits/"]
```

## 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.

```mermaid theme={null}
graph LR
    A["Shared/Blank<br>Blank comune"] --> B["Livewire/Blank<br>Minimale Livewire"]
    B --> C["Shared/Base<br>Base comune"]
    C --> D["Livewire/Base<br>Base Livewire"]
    D --> E["Shared/Fortify<br>Fortify comune"]
    E --> F["Livewire/Fortify<br>Fortify Livewire"]
    F --> G["build/<br>kit finito"]
```

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.

<Steps>
  <Step title="Spostati nella directory orchestrator e builda il kit">
    ```bash theme={null}
    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.

    ```bash theme={null}
    php artisan build --kit=vue
    php artisan build --kit=react --workos
    php artisan build --kit=livewire --teams
    php artisan build --kit=vue --workos --teams
    ```
  </Step>

  <Step title="Avvia il kit buildato">
    ```bash theme={null}
    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/`.
  </Step>

  <Step title="Modifica e testa">
    Modifica i file nella directory `build/`. Il watcher rileva le modifiche e le riflette automaticamente nella directory `kits/`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

## Altri comandi di sviluppo

### Lint

```bash theme={null}
# 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

```bash theme={null}
# 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.

```bash theme={null}
# 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/`.

```bash theme={null}
# orchestrator/.env
WORKOS_CLIENT_ID=your_client_id
WORKOS_API_KEY=your_api_key
```

## Stato attuale dello sviluppo

* **Repository GitHub**: [laravel/maestro](https://github.com/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.

<Card title="Repository laravel/maestro" icon="github" href="https://github.com/laravel/maestro">
  Se sei interessato a contribuire agli starter kit, inizia leggendo il README di Maestro.
</Card>

<Card title="Documentazione ufficiale degli starter kit Laravel" icon="book-open" href="https://laravel.com/docs/starter-kits">
  Per l'uso degli starter kit consulta la documentazione ufficiale.
</Card>


## Related topics

- [Laravel PAO — strumento di ottimizzazione dell'output per agenti AI](/it/blog/pao-introduction.md)
- [Laravel Chisel — libreria di script post-installazione per starter kit](/it/blog/chisel-introduction.md)
- [Bundle degli asset con Vite](/it/vite.md)
- [Frontend](/it/frontend.md)
- [Introduzione a Svelte — le basi per usarlo con Inertia × Laravel](/it/blog/svelte-introduction.md)