Forem: catatsumuri

Contributing to Laravel Maestro Starter Kits Without Losing Your Changes

catatsumuri — Thu, 21 May 2026 22:35:18 +0000

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

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

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

Laravel Starter Kit Localization Is Surprisingly Painful

catatsumuri — Sun, 17 May 2026 10:01:21 +0000

About Laravel Starter Kits Since Laravel 12

These are meant to rapidly deploy functionality that is almost essential during the initial launch of an application, including the following:

Layouts
- A typical sidebar layout
- Or a typical header layout
- Breadcrumbs
Authentication
- Basic session management
- Password reminders
- Self-registration
- TOTP-based 2FA
User settings
- Profile
- Light mode / dark mode switching
- Account deletion
Simple dashboard

Provided authentication screen

Part of the user settings

As you can see, this is extremely convenient for getting a project off the ground. However, especially in Japanese-speaking regions, adoption does not seem to be progressing very well. One reason is probably that the functionality is somewhat difficult to understand, but another major factor is likely the effort required for Japanese localization. Nowadays, with AI programming, identifying and rewriting English interfaces is not especially difficult, but not everyone has access to AI development agents, repeatedly translating everything with AI is exhausting, and if you are making an ambitious attempt to support multilingualization as OSS, then Laravel Starter Kits will inevitably run into localization issues.

Laravel Starter Kits Actually Come in About Four Flavors

Even when we say “Laravel Starter Kit,” there are currently about four flavors. First, I want to organize them.

Livewire-based
Inertia.js-based
- React
- Vue
- Svelte

At a broad level, things first split into Livewire and Inertia.js, and under Inertia.js there are three more flavors, each with branches beneath them... This huge number of variations is itself one of the characteristics of this project. Since the localization situation differs between Livewire and Inertia.js, you first need to understand that distinction.

To give the conclusion up front: if you intend to complete your project with Livewire, multilingualization is not especially difficult, and there is already some infrastructure in place. However, if you try to localize Inertia.js, there is no translation mechanism in the Starter Kit’s default state.

Projects for i18n in Laravel

Laravel’s Built-in Translation Mechanism

On the backend side, Laravel itself already has localization functionality, which is reinforced through additional resources provided by Laravel Lang.

Laravel 13 Localization Documentation:

https://laravel.com/docs/13.x/localization

About Laravel-Lang

There has actually been a project called Laravel-Lang for quite a while, and it already provides some multilingualization mechanisms.

https://laravel-lang.com/basic-usage.html

Following the documentation:

composer require laravel-lang/common

This resolves and installs the following dependencies:

laravel-lang/publisher
laravel-lang/lang
laravel-lang/attributes
laravel-lang/http-statuses
laravel-lang/starter-kits

At first glance, it seems like this package might somehow magically handle Starter Kit localization, but reality is not so simple. We’ll look at that later. Simply installing the package only expands files under vendor/, so at this stage, nothing is actually usable yet.

Deploying Into the Actual Project With the lang:add Command

You execute it like this. Here, we’ll only deploy ja.

php artisan lang:add ja

The actual implementation of this command comes from the previously resolved dependency laravel-lang/publisher, which performs the following tasks:

Determine the target locale
Select only enabled plugins from the plugin list
Read the key list from source/...
Read values from locales/{locale}/...
Write them into lang/{locale}.json or lang/{locale}/*.php

In any case, once this command is executed, things should expand like this:

   INFO  Collecting translations...

  LaravelLang\Actions\Plugin ............................................................................. 2.37ms DONE
  LaravelLang\Attributes\Plugin .......................................................................... 0.83ms DONE
  LaravelLang\HttpStatuses\Plugin ........................................................................ 1.28ms DONE
  LaravelLang\Lang\Plugin ................................................................................ 5.90ms DONE
  LaravelLang\StarterKits\Plugin ......................................................................... 1.37ms DONE

   INFO  Storing changes...

  ja.json ................................................................................................ 5.04ms DONE
  ja/actions.php ......................................................................................... 4.65ms DONE
  ja/auth.php ............................................................................................ 0.45ms DONE
  ja/http-statuses.php ................................................................................... 2.02ms DONE
  ja/pagination.php ...................................................................................... 0.55ms DONE
  ja/passwords.php ....................................................................................... 0.52ms DONE
  ja/validation.php

Locale Configuration

As described in the official documentation, this is determined by the APP_LOCALE environment variable, and falls back to APP_FALLBACK_LOCALE if unavailable. Therefore, for Japanese localization, the configuration would typically look like this:

#APP_LOCALE=en
APP_LOCALE=ja
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=en_US

This localizes the backend.

For example, after installing the package and configuring the locale, even 404 pages are immediately translated into Japanese. But this is backend functionality.

Frontend Support

This is where the problem begins.

As mentioned earlier, the situation differs between Livewire and Inertia.js. To say it first: the only thing functioning relatively properly at the moment is Livewire. So let’s start with the Livewire side.

Roughly How Laravel-Lang Builds Translation Files

There are actually two major types of translation files: .json and .php types. Since the frontend mainly uses .json files, I’ll focus on those here.

At this point, the dependency resolution from laravel-lang/common should have expanded the following four files:

vendor/laravel-lang/starter-kits/locales/ja/json.json
vendor/laravel-lang/lang/locales/ja/json.json
vendor/laravel-lang/http-statuses/locales/ja/json.json
vendor/laravel-lang/actions/locales/ja/json.json

These are merged together to ultimately form the file lang/ja.json. However, not everything is blindly copied over; there is actually a filtering stage called source defined beforehand. For example, let’s look at the Livewire one.

https://github.com/Laravel-Lang/starter-kits/blob/main/source/livewire/main/livewire.json

Only the keys listed here are picked up and internally expanded, so this mechanism seems intended to filter out unnecessary keys.

Meanwhile, the current React situation looks like this:

https://github.com/Laravel-Lang/starter-kits/blob/main/source/react/main/react.json

…Yeah.

So let’s look at how the Livewire Starter Kit is actually translated by examining the login screen.

Translating the Livewire Starter Kit Login Screen

https://github.com/laravel/livewire-starter-kit/blob/main/resources/views/pages/auth/login.blade.php

In this case, translation hooks are already embedded throughout the UI from the beginning. For example:

<!-- Remember Me -->
<flux:checkbox name="remember" :label="__('Remember me')" :checked="old('remember')" />

<div class="flex items-center justify-end">
  <flux:button variant="primary" type="submit" class="w-full" data-test="login-button">
    {{ __('Log in') }}
  </flux:button>
</div>

As shown, it passes things through PHP’s translation system using __(). Since Livewire is tightly integrated with the backend (essentially operating in a pure Blade-like manner), this approach is possible.

The Quality of Livewire’s Japanese Resources

So does installing the language pack solve everything? Unfortunately, no. At present, the translation quality is extremely poor, or rather, most of it is untranslated.

https://github.com/Laravel-Lang/starter-kits/blob/main/locales/ja/json.json

Since translation files are generated based on this, there’s honestly no way around fixing it. I’ve been sending PRs and discussing things, so maybe it’ll improve somewhat, but who knows...

https://github.com/Laravel-Lang/starter-kits/pull/1902

https://livewire-starter-kit-ja.catatsumuri.org/login

You can view the current proposal using test@example.com / password

As for Inertia.js UIs Like React

Let’s look at the login screen again. Since we compared the Remember me section earlier, here’s just the corresponding part.

https://github.com/laravel/react-starter-kit/blob/main/resources/js/pages/auth/login.tsx#L76-L94

The strings are written directly into the source code, meaning that whether it’s Japanese or any other language, nothing gets translated as-is (naturally).

Conclusion

That is the current state of localization (i18n) in Laravel Starter Kits. Outside of Livewire, things are honestly pretty rough. For English-speaking users, this tends not to become a major issue, but outside that environment... the problems become extremely apparent. I suspect everyone is just aggressively rewriting UIs using AI or similar tools, but I really wish things were handled a little better. For now, I’ve at least tried contributing Japanese resources through PRs, but in the end, what’s actually going to happen here?