Laravel Maestro Contributor Tutorial

Laravel uses Maestro to build Starter Kits. Documentation for contributing to these kits is scarce.

If you want to add features or fix bugs in a Starter Kit, you need to understand the workflow. This guide explains how to use Maestro correctly.

The Directory Structure

The repository has three main parts:

  • kits/: This holds the actual Starter Kit files. This is the only directory you commit.
  • orchestrator/: This manages the build process and runs the kits.
  • build/: This is a temporary workspace. Maestro creates this when you run a build.

The Development Workflow

Do not work directly in the kits/ directory unless you are updating many files at once. Instead, follow these steps:

  1. Setup the environment Navigate to the orchestrator/ folder. Run composer install and npm install.

  2. Build your target kit Run php artisan build. Choose your framework, variant, and features. This creates the build/ folder.

  3. Run the kit Use composer kit:run from the orchestrator/ folder. This starts the application on port 8000.

  4. Make your changes Open the build/ directory. Find the files you need to change and edit them.

  5. Let the watcher work Maestro uses a watcher. When you save a file in build/, it automatically updates the correct file in the kits/ directory.

  6. Test your changes Stop the kit:run process first. You cannot run tests while the kit is running. From the orchestrator/ folder, run:

  • composer kits:pint (for formatting)
  • composer kits:check (for PHP tests)
  • composer kits:lint (for JavaScript tests)
  1. Commit your work Check your git status. You should see changes in the kits/ folder. Only add the kits/ directory to your commit.

Example: Changing text from "Log in" to "Log on"

  • Edit the blade or component file inside build/.
  • Wait for the watcher to update kits/.
  • Run tests to ensure you did not break other variants.
  • Commit the files in kits/.

This process ensures your contribution stays clean and follows the Maestro architecture.

Source: https://dev.to/catatsumuri/laravel-maestro-contributor-tutorial-2p89