Laravel Maestro — l'orchestrateur de développement des starter kits

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

Qu’est-ce que Maestro ?

Laravel Maestro est un orchestrateur monorepo destiné à gérer, de manière unifiée, les 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.

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

Se placer dans orchestrator et builder le kit

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.

php artisan build --kit=vue
php artisan build --kit=react --workos
php artisan build --kit=livewire --teams
php artisan build --kit=vue --workos --teams

Lancer le kit compilé

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

Modifier et tester

Éditez les fichiers dans le répertoire build/. Le watcher détecte les changements et les répercute automatiquement dans kits/.

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.

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.

Autres commandes de développement

Lint

# 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

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

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

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

Dépôt laravel/maestro

Si vous souhaitez contribuer aux starter kits, commencez par consulter le README de Maestro.

Documentation officielle des starter kits Laravel

Pour l’utilisation des starter kits eux-mêmes, consultez la documentation officielle.

​Qu’est-ce que Maestro ?

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

​Variantes de starter kits

​Stack Livewire (6 variantes)

​Stack Inertia (15 variantes)

​Structure du dépôt

​Système de couches de fichiers

​Flux de contribution

​Autres commandes de développement

​Lint

​Tests navigateur

​Filtrage par flags

​Configuration des variables d’environnement WorkOS

​État actuel du développement

Dépôt laravel/maestro

Documentation officielle des starter kits Laravel

Qu’est-ce que Maestro ?

Quels problèmes cela résout-il ?

Variantes de starter kits

Stack Livewire (6 variantes)

Stack Inertia (15 variantes)

Structure du dépôt

Système de couches de fichiers

Flux de contribution

Autres commandes de développement

Lint

Tests navigateur

Filtrage par flags

Configuration des variables d’environnement WorkOS

État actuel du développement