Laravel Splade Breeze Laravel Package

Getting Started

Check versions first — but the story changed with 2.5.2. Earlier 2.x releases of this package were Laravel 9/10-era. 2.5.2 (PR #23) adds declared support for PHP 8.3 and Laravel 11, so the previous advice to treat this as read-only reference material on Laravel 11 no longer holds outright. What hasn't changed: the rest of the 2.5.2 changelog is Dependabot noise (GitHub Actions versions for fetch-metadata, checkout, laravel-pint-action, git-auto-commit-action) — CI plumbing, zero runtime effect. So 2.5.2 is really one meaningful commit plus housekeeping: a single data point of maintenance, not a revival. Confirm the constraint that actually bites — the protonemedia/laravel-splade version pinned in composer.json — still resolves on your Laravel version, because the scaffolding supporting L11 doesn't guarantee the Splade core it pins does.

Minimal path for a fresh app:

composer require protonemedia/laravel-splade-breeze:^2.5.2
php artisan splade-breeze:install   # publishes controllers, routes, views, config
npm install && npm run dev
php artisan migrate

Pin ^2.5.2 explicitly if you're on Laravel 11 or PHP 8.3 — older tags will fail composer resolution or install a scaffold wired for Laravel 10 conventions.

The installer is the whole point: it copies Breeze-style auth scaffolding (login, register, forgot/reset password, email verification, profile update) into your app as Splade Blade views rather than Inertia/React/Vue pages. There is no API layer and no separate frontend app — the pages are Blade files that use Splade's Vue components (<x-splade-form>, <x-splade-modal>, Toast, etc.) for SPA-like behavior.

Where to look first, in order:

1. routes/auth.php — the full auth route surface, including throttle middleware and signed verification routes.
2. app/Http/Controllers/Auth/* — LoginController, RegisterController, PasswordResetLinkController, NewPasswordController, EmailVerificationController, ConfirmablePasswordController.
3. resources/views/auth/* — the actual day-to-day reference material. This is the best Splade tutorial you'll get from this repo.
4. resources/js/app.js and tailwind.config.js — whether the installer wired up Splade's Vue plugin and content paths.
5. config/splade.php — only if you installed Splade separately.

First use case: bootstrap a small internal app where you want login/registration and a profile page without committing to Inertia. Run the installer, migrate, log in, and then immediately read the published resources/views/auth/login.blade.php to see how <x-splade-form> maps validation errors, redirects, and toasts.

Implementation Patterns

Treat it as a scaffold, not a library. Every file it ships lands in your repo and is yours to edit. The correct pattern is: install once, commit the generated files as "yours," and never composer update into a surprise. Vendor-forking is the intended workflow, not a workaround.

The form component is the integration contract. Splade's <x-splade-form> submits via fetch, expects JSON 422 validation responses, and renders errors inline. Any controller you write that these views post to should return standard Laravel validation responses ($request->validate([...])) — do not hand-roll redirect()->back()->withErrors() for XHR requests, or errors silently disappear.

Reuse the auth views as a pattern library. The login/register/profile views demonstrate the three idioms you'll use everywhere:

• <x-splade-form :default="$user"> for create/edit, with @submit handlers for client-side transitions.
• <x-splade-modal> for confirmations (password confirm, delete account).
• Toast/flash feedback after redirects.

Copy these shapes into your CRUD screens rather than inventing new ones.

Route layout. Auth routes live in their own file with guest/auth groups. Keep it that way; if you add two-factor or social login later, you extend routes/auth.php instead of scattering routes into web.php. Preserve ->middleware('throttle:6,1') on the login POST.

Email verification uses signed URLs plus the verified middleware. The view pattern is a full-page prompt with a "resend" form; if you replace the mail driver with a queued one, keep the signed route intact.

Profile updates are the second-best reference: ProfileController shows the Hash::check + Password::defaults() pattern, Splade's form re-population, and how to flash a success toast without a page reload. Lift this wholesale for any "settings" page.

Testing. The scaffold ships feature tests. Run php artisan test --filter=Auth after install to confirm the wiring before you touch anything — on Laravel 11 this is your fastest signal that PR #23's support claim actually holds for your app. Use Mail::fake() and Notification::fake() rather than a real mailer when iterating on reset/verify flows.

Interop with an existing app. If you already have Breeze installed, do not run the installer — it will overwrite routes/web.php, resources/js/app.js, and your Tailwind config. Instead, copy the resources/views/auth subtree and the auth controllers by hand, then manually merge the two route files.

Upgrading from 2.5.1. For the runtime code this is a no-op: the Laravel 11 / PHP 8.3 change is in composer.json constraints, not in the published stubs. Because the scaffold is vendored into your app, composer update will not rewrite your app/Http/Controllers/Auth or resources/views/auth — you'll need to re-run the installer on a throwaway branch and diff if you want the constraint changes reflected in what you ship.

Gotchas and Tips

• Version support is a declaration, not a guarantee. 2.5.2 says Laravel 11 + PHP 8.3, but the release is one compatibility PR on top of an otherwise dependabot-only history. Verify with a real install-and-migrate on your target version rather than trusting the constraint string; the pinned Splade core is the likelier failure point than this scaffold.
• Archived/low-maintenance means slow security response. Auth scaffolding is security-adjacent code. Pin exact versions in composer.json, and keep the migration path to stock Laravel Breeze (or Splade's own install command) documented. With a tiny star count and no dependents, there is no community backstop — a single compatibility PR doesn't change that.
• The installer is destructive. It publishes over existing files. Commit a clean tree first, run it, then git diff line by line. The most common failure is a silently truncated web.php.
• Splade requires a real build step. In production you need npm run build and the @splade head directive in your layout. Missing either yields forms that look fine but don't submit — a confusing 200-with-no-effect failure. Check the rendered <head> for Splade's meta tags when debugging.
• Duplicate Splade registration. The package pins an older protonemedia/laravel-splade. If you also composer require Splade directly, you can end up with two Vue plugin registrations and doubled reactivity handlers. Let the scaffold own the dependency, or install Splade yourself and skip the scaffold's install path entirely. After 2.5.2, re-check which Splade version you actually resolved — the constraint may have moved.
• CSRF for custom JS. <x-splade-form> handles the token, but any bespoke fetch/axios call you add needs X-CSRF-TOKEN from the meta tag. Symptom: 419s only on your custom endpoints.
• Throttling is easy to lose. If you hand-merge auth routes, verify with php artisan route:list --path=login that the throttle middleware survived. Losing it is a quiet security regression.
• Mail config before testing reset. Password reset flows fail opaquely if MAIL_* isn't set. Use MAIL_MAILER=log locally and read storage/logs/laravel.log for the signed link.
• Debugging order: browser console for unregistered Vue components → network tab for 422/419 shapes → php artisan route:list for middleware → npm run build output for Tailwind content paths. Splade errors usually surface as "component not resolved," which is almost always a build/config issue, not PHP.
• Extension points are file edits. There's no service provider hook or publishable view override worth using here — the scaffold is the extension point. Document loudly in your README that app/Http/Controllers/Auth is vendored code you've modified, so the next developer doesn't try to upgrade it.