> ## 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'orchestrateur de développement des starter kits

> Analyse du nouveau dépôt officiel Laravel « Maestro ». Découvrez le mécanisme d'orchestration qui gère plusieurs variantes de starter kits dans un seul monorepo et facilite les contributions.

<Info>
  Cet article s'appuie sur une exploration du code source. La documentation officielle n'existe pas encore, et il s'agit d'un dépôt en pré-release (à la date d'avril 2026).
</Info>

## Qu'est-ce que Maestro ?

[Laravel Maestro](https://github.com/laravel/maestro) est un orchestrateur monorepo destiné à gérer, de manière unifiée, les [starter kits](https://laravel.com/starter-kits) de Laravel.

Les starter kits Laravel se déclinent en plusieurs stacks (React, Vue, Svelte via Inertia, et Livewire), et chacune se combine à différents modes d'authentification (Fortify, WorkOS) et options (Teams, Blank), donnant plus de 15 variantes. Maestro gère toutes ces variantes dans un seul dépôt et propage automatiquement les changements vers chaque dépôt de starter kit.

```mermaid theme={null}
graph TD
    A["laravel/maestro<br>(monorepo)"] --> B["orchestrator/<br>Outil de build"]
    A --> C["kits/<br>Fichiers sources"]
    A --> D["browser_tests/<br>Tests navigateur"]
    B --> E["Assemble les variantes<br>via la commande build"]
    E --> F["build/<br>Kit compilé"]
    F --> G["composer kit:run<br>lance et surveille"]
    G --> H["Répercute les changements<br>automatiquement dans kits/"]
```

## Quels problèmes cela résout-il ?

Quand les starter kits se déclinent en de multiples variantes, appliquer une même correction à toutes devient laborieux. Par exemple, corriger la validation du formulaire d'authentification sur React, Vue, Svelte et Livewire via des PR séparées est peu efficace.

Maestro résout ce problème avec une « structure hiérarchique en couche partagée et couche par variante ». L'orchestrateur détermine à quelle couche apporter le changement et l'applique automatiquement au bon endroit.

## Variantes de starter kits

Maestro gère les starter kits organisés en deux stacks.

### Stack Livewire (6 variantes)

| Variante                        | Description                                   |
| ------------------------------- | --------------------------------------------- |
| Blank                           | Configuration minimale sans authentification  |
| Fortify                         | Authentification via Laravel Fortify          |
| Fortify (Multi-file Components) | Vues Blade séparées en fichiers de composants |
| Fortify (Teams)                 | Authentification Fortify + support des Teams  |
| WorkOS                          | Authentification via WorkOS                   |
| WorkOS (Teams)                  | Authentification WorkOS + support des Teams   |

### Stack Inertia (15 variantes)

Combinaison des trois frameworks (React, Vue, Svelte) × Blank/Fortify/WorkOS × Teams ou non, soit 15 variantes au total.

## Structure du dépôt

```
laravel/maestro/
├── orchestrator/    # Application Laravel qui pilote le build
│   ├── app/Console/Commands/BuildCommand.php
│   ├── app/Enums/StarterKit.php
│   └── scripts/
├── kits/            # Fichiers sources des starter kits
│   ├── Shared/      # Fichiers communs à toutes les variantes
│   ├── Livewire/    # Fichiers spécifiques à Livewire
│   └── Inertia/     # Fichiers spécifiques à Inertia (React/Vue/Svelte)
└── browser_tests/   # Tests navigateur
    ├── bootstrap/
    ├── common/
    └── teams/
```

Le répertoire `orchestrator` est lui-même une application Laravel qui pilote la compilation et l'exécution des starter kits.

## Système de couches de fichiers

Le cœur de Maestro est le mécanisme qui « superpose des couches pour assembler le starter kit ». Pour Livewire (Fortify), les fichiers sont copiés dans l'ordre suivant, les couches ultérieures écrasant les précédentes.

```mermaid theme={null}
graph LR
    A["Shared/Blank<br>Blank partagé"] --> B["Livewire/Blank<br>Livewire minimal"]
    B --> C["Shared/Base<br>Base partagée"]
    C --> D["Livewire/Base<br>Base Livewire"]
    D --> E["Shared/Fortify<br>Fortify partagé"]
    E --> F["Livewire/Fortify<br>Fortify Livewire"]
    F --> G["build/<br>Kit assemblé"]
```

Cette hiérarchie établit une règle claire : « les modifications communes à tous les kits vont dans `Shared/`, celles propres à Livewire dans `Livewire/` ».

## Flux de contribution

Vous contribuez aux starter kits via ce dépôt Maestro, et non via chaque dépôt de starter kit.

<Steps>
  <Step title="Se placer dans orchestrator et builder le kit">
    ```bash theme={null}
    cd orchestrator
    php artisan build
    ```

    Un prompt interactif permet de choisir le kit cible et la variante d'authentification. Vous pouvez aussi utiliser directement des flags.

    ```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="Lancer le kit compilé">
    ```bash theme={null}
    composer kit:run
    ```

    Le serveur de développement Laravel et le watcher de fichiers démarrent simultanément. Les modifications faites dans `build/` sont automatiquement copiées vers le bon emplacement dans `kits/`.
  </Step>

  <Step title="Modifier et tester">
    Éditez les fichiers dans le répertoire `build/`. Le watcher détecte les changements et les répercute automatiquement dans `kits/`.
  </Step>

  <Step title="Ouvrir une PR">
    Commitez les changements dans `kits/` et ouvrez une PR. Une fois fusionnée, Maestro pousse automatiquement les modifications vers chaque dépôt de starter kit.
  </Step>
</Steps>

<Warning>
  Le répertoire `build/` est ignoré par git. Faites toutes vos modifications dans `build/` et laissez le watcher les synchroniser vers `kits/` avant de committer.
</Warning>

## Autres commandes de développement

### Lint

```bash theme={null}
# Exécute Pint sur kits et browser_tests (PHP uniquement)
composer kits:pint

# Lint PHP + lint front-end de chaque variante Inertia
composer kits:lint

# Cibler un framework spécifique
composer kits:lint -- --vue
composer kits:lint -- --react --svelte
```

### Tests navigateur

```bash theme={null}
# Exécute les tests navigateur pour toutes les variantes
composer kits:browser-tests

# Filtrer par framework / variante
composer kits:browser-tests -- --vue
composer kits:browser-tests -- --livewire --fortify
```

Les tests navigateur reposent sur Pest + Playwright. Le répertoire `browser_tests/` s'organise en trois couches : `bootstrap/` (configuration commune), `common/` (pour Fortify) et `teams/` (pour Teams).

### Filtrage par flags

Chaque commande peut être filtrée en combinant les flags `--livewire`, `--react`, `--svelte`, `--vue` avec `--blank`, `--fortify`, `--workos`, `--teams`.

```bash theme={null}
# Vérifier uniquement les variantes Fortify pour Vue et Svelte
composer kits:check -- --vue --svelte --fortify

# Uniquement les variantes WorkOS de tous les frameworks
composer kits:check -- --workos
```

## Configuration des variables d'environnement WorkOS

Pour builder et exécuter une variante WorkOS, définissez l'ID client et la clé API WorkOS dans `orchestrator/.env`. Lors du build, ces valeurs sont copiées dans le `.env` du répertoire `build/`.

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

## État actuel du développement

* **Dépôt GitHub** : [laravel/maestro](https://github.com/laravel/maestro)
* **Release officielle** : aucune (pas de tag/version publiés)
* **Dernier commit** : avril 2026 (développement actif)
* **Version PHP requise** : ^8.2
* **Version Laravel** : ^13.0

Maestro n'est pas un package destiné à l'utilisateur final : c'est une **infrastructure de développement** pour l'équipe Laravel et les contributeurs. Les starter kits eux-mêmes (`laravel/starter-kit-react`, etc.) sont générés et maintenus depuis ce monorepo par Maestro.

<Card title="Dépôt laravel/maestro" icon="github" href="https://github.com/laravel/maestro">
  Si vous souhaitez contribuer aux starter kits, commencez par consulter le README de Maestro.
</Card>

<Card title="Documentation officielle des starter kits Laravel" icon="book-open" href="https://laravel.com/docs/starter-kits">
  Pour l'utilisation des starter kits eux-mêmes, consultez la documentation officielle.
</Card>


## Related topics

- [Laravel Chisel — la bibliothèque de scripts post-installation des starter kits](/fr/blog/chisel-introduction.md)
- [Créer un starter kit Laravel](/fr/advanced/starter-kit-creation.md)
- [Laravel Console Starter](/fr/packages/laravel-console-starter/index.md)
- [Tutoriel - Laravel Console Starter](/fr/packages/laravel-console-starter/tutorial.md)
- [Laravel PAO — outil d'optimisation des sorties pour les agents IA](/fr/blog/pao-introduction.md)