Tomato Breeze Laravel Package

Technical Evaluation

Architecture fit. This is a scaffold, not a library, and that distinction is the whole evaluation. Installing it copies auth routes, controllers, views, layouts, and Tailwind config into the application as first-party code. There is no composer update path to upstream fixes. From a portfolio standpoint that is actually the right shape for an auth + app-shell layer: it replaces roughly two to three sprint-weeks of design, frontend, and QA work (login, registration, logout, password reset, email verification, profile, layout, nav, theme toggle) with a scaffold-and-rebrand pass. The strategic value is not the Breeze scaffolding — Laravel ships that free — it is first-class RTL and dark mode out of the box. The package is also a de facto commitment to Splade (Blade-rendered Vue 3, no Inertia, no Livewire), and that stack decision is easy to make by stealth if we are not explicit about it.

Integration feasibility. Low-to-moderate, gated on a spike. Zero stars, zero dependents, last release 2023-04-06 — it predates Laravel 11's slimmed skeleton and Breeze's own restructure. Assume Laravel 9/10, PHP 8.1/8.2, Splade 1.x, Tailwind 3 until a scratch-app spike proves otherwise. A two-hour loop — install on a throwaway laravel:^10.0 project, load /login and /register, toggle dark mode, set dir="rtl" on <html> and confirm the layout doesn't collapse — tells us more than any README. If the target is Laravel 11/12, treat it as a port, not an install (3–5 engineer-days). Decision gate: if porting exceeds ~5 days, take only the RTL/dark Tailwind layer onto stock Breeze and hand-build the rest.

Technical risk. Auth is the surface where stale templates are least acceptable, and this is a 2023-vintage fork of it. Three risks dominate: (1) silent security drift — password reset, signed verification URLs, and session regeneration need explicit diffing against current upstream Breeze before we build product surface; (2) architectural collision — do not run this alongside tomato-admin/Filament or co-install with first-party laravel/breeze; two auth front ends, two theming systems, two upgrade tracks, and a confused web.php; (3) invisible frontend breakage — Splade renders vendor Blade views, so missing vendor globs in Tailwind content purge classes and the UI looks almost right. Separately, APP_URL mismatches break signed email links with a generic 403 that reads like an application bug, and theme flashes white on load if the class is applied after DOMContentLoaded.

Key questions for the decision meeting.

• Which paradigm owns authentication for this app — Splade or Filament? Decide before the second one lands.
• Is Splade already our frontend standard, or is this a stack review disguised as a utility pickup?
• Is RTL a v1 requirement or an aspirational "localization phase"? If aspirational, the strongest reason to look at this package evaporates.
• Is this an internal back-office/admin/MVP/demo surface, or an externally audited, customer-facing auth surface? The answer changes the recommendation.
• Who is the named owner of the auth screens from day one? An unowned auth fork is how password-reset flows rot.

Integration Approach

Stack fit. Good inside or adjacent to the TomatoPHP ecosystem, where admin and UI conventions already match sibling packages. Poor as a lone dependency in a stack that has standardized elsewhere. If Splade is not our standard, the RTL/dark payoff gets buried under a stack migration nobody budgeted.

Migration path — vendor it, don't depend on it. This is the single most important operational step: after the spike is green, git add -A, commit the generated scaffold with the upstream commit SHA in the message, then composer remove tomatophp/tomato-breeze. Keep the code, drop the runtime dependency, tag the fork, and register it as self-maintained. Also decide route ownership deliberately — published routes in their own file, required from bootstrap/app.php (Laravel 11+) or RouteServiceProvider (10 and below) — so middleware and throttle on login and password-reset POSTs live in one place.

Compatibility. Pin everything and commit the lock. Splade, Tailwind, Vue, and the Prologue PHP packages move independently; record a tested version matrix in the repo. Add ./vendor/prologuephp/**/*.php and ./vendor/tomatophp/**/*.php to Tailwind content and rebuild before debugging anything visual. Never patch vendor/tomatophp/... — publish first, edit only the copies. Cherry-picking path for teams already on stock Breeze: lift only the Tailwind config changes, the CSS variable/theme layer, and the layout's dir/class handling — one to two days, captures most of the differentiation, avoids re-scaffolding.

Sequencing. (1) Stack decision and auth-owner decision. (2) Throwaway spike on the real target version, five flows × two directions × two themes. (3) Post-install hardening: diff auth controllers against current upstream Breeze, re-apply security fixes since April 2023, confirm hashed reset tokens with expiry, signed verification links, session regeneration on login. (4) Vendor and commit the fork. (5) Rebrand pass — logo, primary color scale, font, semantic palette in tailwind.config.js — half a day, 90% of perceived customization. (6) Feature surface, with validation in FormRequests and customization of registration/profile extending the published controllers rather than forking the flow. (7) Feature tests for all four flows (Mail::fake() and assert on the signed URL) plus an RTL/dark visual checklist in the PR template.

Operational Impact

Maintenance. This is a recurring budget line item, not a one-time pickup. Starter kits don't upgrade — they get re-scaffolded. Plan ~2–4 engineer-days per Laravel major to re-port or re-verify. Portfolio-level framing: every new Laravel app faces the same build-vs-fork decision for auth and shell, so this is a reusable template decision worth codifying, not a one-off procurement.

Support. Zero stars means zero Stack Overflow answers; every edge case is discovered by reading the source. That is manageable — it's a small codebase and the published controllers are faster to read than a fix that doesn't exist — but it must be staffed, not assumed. The four extension points that cover nearly every customization: published views, layout components (theme and direction live here), form requests (validation), and the routes file (middleware and rate limiting). Anything requiring more is a signal we're using the scaffold wrong.

Scaling. Good for internal back-office dashboards, admin apps, MVPs, hackathon/POC builds, and stakeholder demos. Poor for long-lived, externally audited, customer-facing products where auth is a compliance surface — that is a deliberate speed-over-longevity bet, and it should be recorded as one rather than discovered in an audit.

Failure modes to plan for. Auth bugs are quiet: password reset and verification failures surface as a generic redirect or 403, not an exception. Runbook order — php artisan route:list --path=auth, storage/logs/laravel.log, a throwaway Mail::fake() test to inspect the generated URL, then config:clear / view:clear (stale cache after publishing views accounts for a surprising share of "the change didn't apply"). RTL regressions do not fail CI; plan a manual visual pass per release or wire a Playwright screenshot diff. Test email against the real transport in staging, not just the log driver. Persist the theme in localStorage and apply it with a blocking inline script in <head> to kill the flash.

Ramp-up. Small: the fork-and-own posture is learnable in days, and the reading surface is four files. The ramp-up cost is concentrated in the first hardening pass, not in daily use. Budget it explicitly, name the owner, and put the fork SHA and version matrix in the repo so the next engineer inherits a decision rather than an archaeology project.