> ## 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 — Orquestador de desarrollo de starter kits

> Investigación del nuevo repositorio oficial de Laravel «Maestro». Se explica el mecanismo del orquestador que gestiona múltiples variantes de starter kits en un único monorepo y hace más eficientes las contribuciones.

<Info>
  Este artículo se basa en la investigación del código fuente. Todavía no existe documentación oficial y es un repositorio previo al lanzamiento (a fecha de abril de 2026).
</Info>

## ¿Qué es Maestro?

[Laravel Maestro](https://github.com/laravel/maestro) es un orquestador monorepo para gestionar de forma centralizada la familia de [starter kits](https://laravel.com/starter-kits) de Laravel.

Los starter kits de Laravel tienen múltiples stacks: React, Vue, Svelte (Inertia) y Livewire, y además existen más de 15 variantes que combinan el método de autenticación (Fortify, WorkOS) y opciones (Teams, Blank) para cada uno. Maestro proporciona un mecanismo que gestiona todas esas variantes en un solo repositorio y refleja automáticamente los cambios en cada repositorio de starter kit.

```mermaid theme={null}
graph TD
    A["laravel/maestro<br>(monorepo)"] --> B["orchestrator/<br>Herramientas de build"]
    A --> C["kits/<br>Archivos fuente"]
    A --> D["browser_tests/<br>Pruebas de navegador"]
    B --> E["Ensamblado de variantes<br>con el comando build"]
    E --> F["build/<br>Kits ya construidos"]
    F --> G["Arranque y watch<br>con composer kit:run"]
    G --> H["Refleja automáticamente<br>los cambios en kits/"]
```

## ¿Qué problema resuelve?

Cuando los starter kits están divididos en muchas variantes, reflejar una única corrección en todas las variantes se vuelve engorroso. Por ejemplo, sacar PRs individuales de una corrección de validación de un formulario de autenticación en React, Vue, Svelte y Livewire es ineficaz.

Maestro resuelve este problema con una "estructura jerárquica de capa compartida y capa de variante". El orquestador determina en qué capa debe añadirse el cambio y se aplica automáticamente en el lugar más adecuado.

## Variantes de los starter kits

Los starter kits que Maestro gestiona se componen de dos stacks.

### Stack Livewire (6 variantes)

| Variante                        | Descripción                                                         |
| ------------------------------- | ------------------------------------------------------------------- |
| Blank                           | Configuración mínima sin autenticación                              |
| Fortify                         | Autenticación mediante Laravel Fortify                              |
| Fortify (Multi-file Components) | Configuración con vistas Blade separadas en archivos de componentes |
| Fortify (Teams)                 | Autenticación Fortify + soporte de Teams                            |
| WorkOS                          | Autenticación mediante WorkOS                                       |
| WorkOS (Teams)                  | Autenticación WorkOS + soporte de Teams                             |

### Stack Inertia (15 variantes)

Existen 15 variantes en total como combinación de 3 frameworks (React, Vue, Svelte) × Blank/Fortify/WorkOS × con o sin Teams.

## Estructura del repositorio

```
laravel/maestro/
├── orchestrator/    # App Laravel que gestiona el build
│   ├── app/Console/Commands/BuildCommand.php
│   ├── app/Enums/StarterKit.php
│   └── scripts/
├── kits/            # Archivos fuente de los starter kits
│   ├── Shared/      # Archivos comunes a todas las variantes
│   ├── Livewire/    # Archivos específicos de Livewire
│   └── Inertia/     # Archivos específicos de Inertia (React/Vue/Svelte)
└── browser_tests/   # Pruebas de navegador
    ├── bootstrap/
    ├── common/
    └── teams/
```

El propio directorio `orchestrator` es una aplicación Laravel que gestiona la construcción y ejecución de los starter kits.

## Sistema de jerarquía de archivos

El núcleo de Maestro es el mecanismo de "apilar capas para ensamblar un starter kit". En el caso de Livewire (Fortify), los archivos se copian en el siguiente orden y las capas posteriores sobrescriben a las anteriores.

```mermaid theme={null}
graph LR
    A["Shared/Blank<br>Blank común"] --> B["Livewire/Blank<br>Config. mínima Livewire"]
    B --> C["Shared/Base<br>Base común"]
    C --> D["Livewire/Base<br>Base Livewire"]
    D --> E["Shared/Fortify<br>Fortify común"]
    E --> F["Livewire/Fortify<br>Fortify Livewire"]
    F --> G["build/<br>Kit completo"]
```

Gracias a esta jerarquía queda una regla clara: "los cambios comunes a todos los kits van en `Shared/`; los específicos de Livewire, en `Livewire/`".

## Flujo de contribución

Las contribuciones a los starter kits se hacen en este repositorio Maestro, no en los repositorios individuales de cada starter kit.

<Steps>
  <Step title="Ve al directorio orchestrator y construye el kit">
    ```bash theme={null}
    cd orchestrator
    php artisan build
    ```

    Selecciona el kit objetivo y la variante de autenticación mediante prompts interactivos. También puedes indicarlos directamente con 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="Arranca el kit construido">
    ```bash theme={null}
    composer kit:run
    ```

    El servidor de desarrollo de Laravel y un file watcher arrancan a la vez. Los cambios realizados en el directorio `build/` se copian automáticamente al lugar adecuado de `kits/`.
  </Step>

  <Step title="Haz cambios y pruébalos">
    Edita archivos dentro del directorio `build/`. El watcher detecta los cambios y los refleja automáticamente en el directorio `kits/`.
  </Step>

  <Step title="Crea el PR">
    Confirma los cambios sobre el directorio `kits/` y crea el PR. Al hacer merge, Maestro hace push automáticamente de los cambios a cada repositorio de starter kit.
  </Step>
</Steps>

<Warning>
  El directorio `build/` está en gitignore. Haz todos los cambios dentro de `build/`, deja que el watcher los sincronice a `kits/` y luego haz commit.
</Warning>

## Otros comandos de desarrollo

### Lint

```bash theme={null}
# Ejecuta Pint en kits y browser_tests (solo PHP)
composer kits:pint

# Lint de PHP + lint de frontend para cada variante Inertia
composer kits:lint

# Restringir a un framework concreto
composer kits:lint -- --vue
composer kits:lint -- --react --svelte
```

### Pruebas de navegador

```bash theme={null}
# Ejecuta las pruebas de navegador de todas las variantes
composer kits:browser-tests

# Restringir a un framework o variante concreta
composer kits:browser-tests -- --vue
composer kits:browser-tests -- --livewire --fortify
```

Las pruebas de navegador funcionan con Pest + Playwright. Los tests del directorio `browser_tests/` están organizados en 3 capas: `bootstrap/` (config común), `common/` (para Fortify) y `teams/` (para Teams).

### Filtrado con flags

Cada comando puede combinar las flags `--livewire`, `--react`, `--svelte`, `--vue` con `--blank`, `--fortify`, `--workos` y `--teams` para restringir el objetivo.

```bash theme={null}
# Comprobar solo las variantes Fortify de Vue y Svelte
composer kits:check -- --vue --svelte --fortify

# Solo variantes WorkOS de todos los frameworks
composer kits:check -- --workos
```

## Configuración de variables de entorno de WorkOS

Cuando construyas y ejecutes variantes WorkOS, configura el client ID y la API key de WorkOS en `orchestrator/.env`. Durante el build, esos valores se copian al archivo `.env` del directorio `build/`.

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

## Estado actual de desarrollo

* **Repositorio de GitHub**: [laravel/maestro](https://github.com/laravel/maestro)
* **Release oficial**: no (no hay tags ni releases publicadas)
* **Último commit**: abril de 2026 (en desarrollo activo)
* **Versión de PHP requerida**: ^8.2
* **Versión de Laravel**: ^13.0

Maestro no es un paquete dirigido al usuario final, sino que funciona como **infraestructura de desarrollo** para el equipo de Laravel y los contribuidores. Los propios starter kits (`laravel/starter-kit-react`, etc.) se generan y gestionan desde este monorepo mediante Maestro.

<Card title="Repositorio laravel/maestro" icon="github" href="https://github.com/laravel/maestro">
  Si te interesa contribuir a los starter kits, comienza revisando el README de Maestro.
</Card>

<Card title="Documentación oficial de los starter kits de Laravel" icon="book-open" href="https://laravel.com/docs/starter-kits">
  Para el uso de los propios starter kits, consulta la documentación oficial.
</Card>


## Related topics

- [Laravel Chisel — Biblioteca de scripts de post-instalación para starter kits](/es/blog/chisel-introduction.md)
- [Cómo crear un starter kit de Laravel](/es/advanced/starter-kit-creation.md)
- [Laravel PAO — Herramienta de optimización de salida para agentes de IA](/es/blog/pao-introduction.md)
- [Starter kits](/es/starter-kits.md)
- [Laravel Console Starter](/es/packages/laravel-console-starter/index.md)