> ## 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 — 스타터 킷 개발의 오케스트레이터

> Laravel 공식의 새 리포지토리 'Maestro'를 조사합니다. 여러 스타터 킷 배리언트를 하나의 모노레포로 관리하여 컨트리뷰션을 효율화하는 오케스트레이터의 구조를 설명합니다.

<Info>
  이 글은 소스 코드 조사에 기반한 정보입니다. 공식 문서는 아직 존재하지 않으며, 정식 릴리스 전의 리포지토리입니다 (2026년 4월 시점).
</Info>

## Maestro란

[Laravel Maestro](https://github.com/laravel/maestro)는 Laravel의 [스타터 킷](https://laravel.com/starter-kits) 군을 일원 관리하기 위한 모노레포형 오케스트레이터입니다.

Laravel의 스타터 킷에는 React · Vue · Svelte (Inertia)와 Livewire라는 복수의 스택이 있고, 게다가 각각에 인증 방식(Fortify · WorkOS)이나 옵션(Teams · Blank)을 조합한 15종 이상의 배리언트가 존재합니다. Maestro는 이 모든 배리언트를 단일 리포지토리에서 관리하고, 변경을 각 스타터 킷 리포지토리로 자동 반영하는 구조를 제공합니다.

```mermaid theme={null}
graph TD
    A["laravel/maestro<br>(모노레포)"] --> B["orchestrator/<br>빌드 도구"]
    A --> C["kits/<br>소스 파일"]
    A --> D["browser_tests/<br>브라우저 테스트"]
    B --> E["build 명령으로<br>배리언트 조립"]
    E --> F["build/<br>빌드된 킷"]
    F --> G["composer kit:run<br>으로 기동 · 워치"]
    G --> H["변경을 kits/에<br>자동 반영"]
```

## 어떤 문제를 해결하는가

스타터 킷이 다수의 배리언트로 나뉘어 있으면, 하나의 수정을 전 배리언트에 반영하는 작업이 번잡해집니다. 예를 들어 인증 폼의 유효성 검증 수정을 React · Vue · Svelte · Livewire 각각에 개별 PR을 내는 것은 비효율적입니다.

Maestro는 이 문제를 "공유 레이어와 배리언트 레이어의 계층 구조"로 해결합니다. 변경을 어느 레이어에 가해야 할지를 오케스트레이터가 판단하여, 가장 적절한 장소에 자동으로 적용됩니다.

## 스타터 킷의 배리언트

Maestro가 관리하는 스타터 킷은 두 개의 스택으로 구성됩니다.

### Livewire 스택 (6배리언트)

| 배리언트                            | 설명                       |
| ------------------------------- | ------------------------ |
| Blank                           | 인증 없는 최소 구성              |
| Fortify                         | Laravel Fortify에 의한 인증   |
| Fortify (Multi-file Components) | Blade 뷰를 컴포넌트 파일로 분리한 구성 |
| Fortify (Teams)                 | Fortify 인증 + Teams 지원    |
| WorkOS                          | WorkOS에 의한 인증            |
| WorkOS (Teams)                  | WorkOS 인증 + Teams 지원     |

### Inertia 스택 (15배리언트)

React · Vue · Svelte의 3 프레임워크 × Blank · Fortify · WorkOS × Teams 유무의 조합으로, 합계 15배리언트가 존재합니다.

## 리포지토리의 구조

```
laravel/maestro/
├── orchestrator/    # 빌드를 관리하는 Laravel 앱
│   ├── app/Console/Commands/BuildCommand.php
│   ├── app/Enums/StarterKit.php
│   └── scripts/
├── kits/            # 스타터 킷의 소스 파일
│   ├── Shared/      # 전 배리언트 공통 파일
│   ├── Livewire/    # Livewire 고유 파일
│   └── Inertia/     # Inertia 고유 파일 (React/Vue/Svelte)
└── browser_tests/   # 브라우저 테스트
    ├── bootstrap/
    ├── common/
    └── teams/
```

`orchestrator` 디렉터리 자체가 Laravel 애플리케이션이 되어 있으며, 스타터 킷의 빌드와 실행을 관리합니다.

## 파일 계층 시스템

Maestro의 핵심은 "레이어를 겹쳐 스타터 킷을 조립하는" 구조입니다. Livewire (Fortify)의 경우, 다음 순서로 파일이 복사되며, 이후 레이어가 이전 레이어를 덮어쓰기 합니다.

```mermaid theme={null}
graph LR
    A["Shared/Blank<br>공통 블랭크"] --> B["Livewire/Blank<br>Livewire 최소 구성"]
    B --> C["Shared/Base<br>공통 베이스"]
    C --> D["Livewire/Base<br>Livewire 베이스"]
    D --> E["Shared/Fortify<br>공통 Fortify"]
    E --> F["Livewire/Fortify<br>Livewire Fortify"]
    F --> G["build/<br>완성된 킷"]
```

이 계층 덕분에 "모든 킷에 공통되는 수정은 `Shared/`에, Livewire 고유의 수정은 `Livewire/`에 가한다"는 명확한 룰이 만들어져 있습니다.

## 컨트리뷰션의 흐름

스타터 킷으로의 컨트리뷰션은 개별 스타터 킷 리포지토리가 아니라, 이 Maestro 리포지토리에서 수행합니다.

<Steps>
  <Step title="orchestrator 디렉터리로 이동하여 킷 빌드">
    ```bash theme={null}
    cd orchestrator
    php artisan build
    ```

    인터랙티브한 프롬프트로 대상 킷과 인증 배리언트를 선택합니다. 플래그를 사용하여 직접 지정할 수도 있습니다.

    ```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="빌드한 킷 기동">
    ```bash theme={null}
    composer kit:run
    ```

    Laravel의 개발 서버와 파일 워처가 동시에 기동합니다. `build/` 디렉터리에서 수행한 변경은 자동으로 `kits/`의 적절한 위치에 복사됩니다.
  </Step>

  <Step title="변경을 가하고 테스트">
    `build/` 디렉터리 내의 파일을 편집합니다. 워처가 변경을 감지하여 자동으로 `kits/` 디렉터리에 반영합니다.
  </Step>

  <Step title="PR 작성">
    `kits/` 디렉터리로의 변경을 커밋하고 PR을 작성합니다. 머지되면 Maestro가 자동으로 변경을 각 스타터 킷 리포지토리로 푸시합니다.
  </Step>
</Steps>

<Warning>
  `build/` 디렉터리는 gitignore 되어 있습니다. 변경은 모두 `build/` 내에서 수행하고, 워처에 `kits/`로 동기화시킨 후에 커밋해 주세요.
</Warning>

## 그 외 개발 명령

### 린트

```bash theme={null}
# kits와 browser_tests에 Pint 실행 (PHP만)
composer kits:pint

# PHP 린트 + 각 Inertia 배리언트의 프론트엔드 린트
composer kits:lint

# 특정 프레임워크만 대상으로
composer kits:lint -- --vue
composer kits:lint -- --react --svelte
```

### 브라우저 테스트

```bash theme={null}
# 전 배리언트의 브라우저 테스트 실행
composer kits:browser-tests

# 특정 프레임워크 · 배리언트로 좁히기
composer kits:browser-tests -- --vue
composer kits:browser-tests -- --livewire --fortify
```

브라우저 테스트는 Pest + Playwright로 동작합니다. `browser_tests/` 디렉터리에 `bootstrap/` (공통 설정), `common/` (Fortify용), `teams/` (Teams용)의 3층 구조로 테스트가 정리되어 있습니다.

### 플래그에 의한 좁히기

각 명령은 `--livewire` · `--react` · `--svelte` · `--vue` 플래그와 `--blank` · `--fortify` · `--workos` · `--teams` 플래그를 조합하여 대상을 좁힐 수 있습니다.

```bash theme={null}
# Vue와 Svelte의 Fortify 배리언트만 체크
composer kits:check -- --vue --svelte --fortify

# 전 프레임워크의 WorkOS 배리언트만
composer kits:check -- --workos
```

## WorkOS 환경 변수 설정

WorkOS 배리언트를 빌드하여 실행할 경우에는 `orchestrator/.env`에 WorkOS의 클라이언트 ID와 API 키를 설정합니다. 빌드 시에 이 값들이 `build/` 디렉터리의 `.env` 파일에 복사됩니다.

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

## 현재의 개발 상황

* **GitHub 리포지토리**: [laravel/maestro](https://github.com/laravel/maestro)
* **정식 릴리스**: 없음 (버전 태그 · 릴리스는 미공개)
* **최종 커밋**: 2026년 4월 (활발히 개발 중)
* **필요한 PHP 버전**: ^8.2
* **Laravel 버전**: ^13.0

Maestro는 최종 사용자용 패키지가 아니라, Laravel 팀 및 컨트리뷰터용 **개발 인프라**로서 기능하고 있습니다. 스타터 킷 본체(`laravel/starter-kit-react` 등)는 Maestro에 의해 이 모노레포에서 생성 · 관리됩니다.

<Card title="laravel/maestro 리포지토리" icon="github" href="https://github.com/laravel/maestro">
  스타터 킷으로의 컨트리뷰션에 관심이 있으신 분은 우선 Maestro의 README를 확인해 주세요.
</Card>

<Card title="Laravel 스타터 킷 공식 문서" icon="book-open" href="https://laravel.com/docs/starter-kits">
  스타터 킷 자체의 사용법에 대해서는 공식 문서를 참고하세요.
</Card>


## Related topics

- [Laravel 스타터 킷 만드는 법](/ko/advanced/starter-kit-creation.md)
- [스타터 킷](/ko/starter-kits.md)
- [Laravel Fortify와 스타터 킷](/ko/advanced/fortify.md)
- [Laravel Chisel — 스타터 킷의 포스트 인스톨 스크립트 라이브러리](/ko/blog/chisel-introduction.md)
- [2026년 4월 Laravel 업데이트](/ko/blog/changelog/202604.md)