What is Maestro

Maestro is an upstream generator repository for generating and managing Laravel starter kits.

The following starter kit repositories are downstream repositories generated from Maestro, and directly modifying the starter kit side does not propagate changes upstream.

• laravel/react-starter-kit
• laravel/vue-starter-kit
• laravel/svelte-starter-kit

Therefore, when making changes such as the following, you must modify the maestro side instead.

• Shared starter kit bug fixes
• Cross-variant fixes
• Generator-level specification changes
• UI consistency adjustments across stacks

Maestro Structure

Unlike a normal Laravel application, Maestro has the following structure.

• kits/ — source template
• build/ — generated application (generated runtime)
• watcher — synchronization layer from build/ → kits/

Inertia Variant Matrix

The same applies to Vue / Svelte.

If you misunderstand “which side is the source of truth,” unintended rollbacks and unnecessary diffs are very likely to occur.

Basic Principles

kits/ Is the Source of Truth

Any diff that should be committed must exist in kits/. build/ is generated output and should be treated as a working directory for verification, temporary edits, and runtime testing.

You must not commit diffs from the build/ side.

build/ Is Disposable

Treat build/ as something that can always be regenerated. Since its contents change significantly whenever variants are switched, do not place long-term changes, source patches, or persistent fixes directly in build/. Permanent changes belong in kits/.

composer kit:run Is Convenient but Also Dangerous

composer kit:run is a convenience command that launches setup, the Laravel dev server, the Vite dev server, and the watcher together.

However, the watcher treats build/ as authoritative and writes changes back into kits/. As a result, if you start kit:run using an outdated build/, changes in kits/ may get rolled back.

After directly editing kits/, never run composer kit:run with an outdated build/. Always rebuild first.

Initial Setup

git clone https://github.com/laravel/maestro.git
cd maestro/orchestrator

composer install
npm install

Building a Starter Kit

At the beginning of work, expand the target variant into build/.

cd orchestrator

php artisan build --kit=react
php artisan build --kit=vue
php artisan build --kit=svelte

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

The current build target is stored at:

orchestrator/storage/app/private/starter_kit

Starting the Development Server

Do not start directly from build/. Instead, run the following from orchestrator/.

composer kit:run

This command performs the following together:

• composer setup in build/
• Starts the Laravel dev server
• Starts the Vite dev server
• Starts the watcher

Typical endpoints:

• Laravel: http://localhost:8000
• Vite: http://localhost:5173

Safe Workflow

Pattern 1: Edit on the build Side (for temporary verification)

build → kit:run → edit build → verify behavior

Convenient for exploratory UI adjustments. However, since build/ is disposable, it is safer to reorganize the final source patch into kits/.

Pattern 2: Edit on the kits Side (recommended path for PRs)

edit kits → php artisan build ... → composer kit:run → verify

This is the recommended approach when preparing PR patches.

Switching Variants

Do not incrementally update an existing build/. Rebuild every time.

php artisan build --kit=react
php artisan build --kit=vue
php artisan build --kit=svelte

After switching, rerun composer kit:run each time for verification.

Verification Notes

DB Initialization

composer setup only runs up to php artisan migrate --force. If seeded data is required, run the following inside build/.

php artisan migrate:fresh --seed

Removing Stale Files from the Watcher

When switching variants, the watcher may determine some source assets are stale and delete them.

Examples:

• kits/Inertia/Fortify/React/chisel-paths.php
• kits/Inertia/Fortify/Vue/chisel-paths.php
• kits/Inertia/Fortify/Svelte/chisel-paths.php

Handle these separately from the main change set.

Example Routes for Verifying UI Copy Changes

For UI text changes in the Fortify variant, the following routes are usually sufficient to verify the primary flows.

• /login
• /user/confirm-password
• /verify-email
• /settings/security
• /settings/appearance
• /settings/profile

Since WorkOS has a higher verification cost, prioritizing Fortify variants is acceptable for minor changes.

How to Think About Staging

If the PR’s main purpose is a UI copy change, then only stage the text-related diffs.

The following should generally be separated:

• chisel-paths.php deleted by the watcher
• Temporary fixes in build/
• Assertions for browser tests
• Unrelated runtime bug fixes

# Instead of git add ., explicitly add target files
git add kits/path/to/changed-file.blade.php

Pre-PR Checklist

• [ ] Are there any staged diffs from build/?
• [ ] Are stale deletions from the watcher mixed in?
• [ ] Are there unnecessary cross-variant diffs?
• [ ] Are temporary browser test changes still present?
• [ ] Did you check git diff --cached?
• [ ] Is the source of truth correctly on the kits/ side?

Summary

If you handle Maestro like a normal Laravel app, diff rollbacks and unnecessary commits become very easy to trigger. To create PRs safely, maintain the following sequence.

Safe PR Flow

1. Apply changes in kits/
2. Rebuild with php artisan build ...
3. Verify with composer kit:run
4. Stage only intended diffs
5. Separate watcher/browser-test side effects