DEV Community

catatsumuri
catatsumuri

Posted on

Contributing to Laravel Maestro Starter Kits Without Losing Your Changes

#opensource #laravel #php

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

variant build command starter_kit
React Fortify php artisan build --kit=react react
React WorkOS php artisan build --kit=react --workos react-workos
React Fortify + Teams php artisan build --kit=react --teams react-teams
React WorkOS + Teams php artisan build --kit=react --workos --teams react-workos-teams

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

The current build target is stored at:

orchestrator/storage/app/private/starter_kit
Enter fullscreen mode Exit fullscreen mode

Starting the Development Server

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

composer kit:run
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)