Breeze Laravel Package

Getting Started

Minimal Setup

1. Installation (Updated for Laravel 13+ compatibility):

   composer require laravel/breeze --dev
   php artisan breeze:install [stack]  # Choose: blade, react, vue, or api
   npm install && npm run dev
   php artisan migrate
   

   • Note: For Laravel 13+, bootstrap.js is no longer auto-imported (fixed in v2.4.2). Ensure your resources/js/app.js manually includes:

     import './bootstrap'; // Explicit import for Laravel 13+
     

2. First Use Case:

   • Test pre-built auth routes (/login, /register, /dashboard).
   • Customize resources/views/auth/ (Blade) or resources/js/Pages/ (React/Vue).
   • Laravel 13+: Verify resources/js/bootstrap.js exists (create if missing) with:

     import { createApp, h } from 'vue';
     import { createInertiaApp } from '@inertiajs/vue3';
     // ... rest of config
     

3. Key Files to Inspect:

   • app/Http/Controllers/Auth/ (Logic unchanged).
   • routes/web.php (Middleware groups may need adjustment for Laravel 13+).
   • resources/js/bootstrap.js (Critical for Laravel 13+ stacks).

Implementation Patterns

Core Workflows

1. Authentication Flow (Updated for Laravel 13+)

• Blade/Inertia: No changes to auth logic, but ensure bootstrap.js is imported in app.js:

  // resources/js/app.js
  import './bootstrap'; // Required for Laravel 13+
  import { createApp, h } from 'vue';
  

• API Stack: Sanctum remains unchanged. For Laravel 13+, confirm SanctumServiceProvider is registered in config/app.php:

  'providers' => [
      Laravel\Sanctum\SanctumServiceProvider::class,
  ],
  

2. Middleware Integration (Laravel 13+ Note)

• Protected Routes: Use auth middleware from Illuminate\Auth\Middleware\Authenticate:

  Route::middleware(['auth', 'verified'])->group(function () {
      Route::get('/dashboard', DashboardController::class);
  });
  

• API Middleware: Sanctum’s auth:sanctum works as before, but verify config/sanctum.php includes:

  'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', 'localhost,127.0.0.1:3000')),
  

3. Customizing Auth Logic

• Override controllers (e.g., app/Http/Controllers/Auth/RegisteredUserController.php):

  public function register(Request $request) {
      $validated = $request->validate([
          'name' => 'required|string|max:255',
          'email' => 'required|email|unique:users',
          'password' => ['required', 'confirmed', 'min:8'],
      ]);
      return User::create($validated);
  }
  

• Laravel 13+: Use Illuminate\Validation\Rules\Password for stricter defaults:

  'password' => ['required', 'confirmed', Rules\Password::defaults()],
  

4. Email Verification

• Trigger manually:

  $user->sendEmailVerificationNotification();
  

• Customization: Extend VerifyEmail notification (unchanged):

  public function toMail($notifiable) {
      return (new MailMessage)
          ->line('Verify your email')
          ->action('Verify', url('/verify-email').'?token='.$notifiable->createVerificationToken());
  }
  

5. Password Reset

• Override broker() in ResetPasswordController:

  protected function broker() {
      return Password::broker('ui')->tokensExpireAfter(CarbonInterval::hours(24));
  }
  

6. Session Handling (Blade)

• Access session data:

  @auth
      <p>Welcome, {{ auth()->user()->name }}!</p>
  @endauth
  

• Laravel 13+: Ensure session() helper is available via Illuminate\Session\Middleware\StartSession.

7. Inertia.js (React/Vue)

• Share data:

  return Inertia::render('Dashboard', ['stats' => $this->getStats()]);
  

• Laravel 13+: Confirm inertia.js is loaded in resources/js/app.js:

  import { createInertiaApp } from '@inertiajs/vue3';
  

8. API Stack (Sanctum)

• Attach tokens:

  $token = $user->createToken('api-token')->plainTextToken;
  

• Laravel 13+: Verify config/sanctum.php includes:

  'expiring_token_lifetime' => CarbonInterval::hours(1),
  

Integration Tips

Frontend-Backend Sync

• Shared Types: Use spatie/laravel-typescript-transformer (unchanged):

  #[AsTypeScriptType]
  class User extends Authenticatable { ... }
  

• Laravel 13+: Ensure resources/js/shims-vue.d.ts targets Vue 3:

  declare module '@inertiajs/core' {
      interface PageProps {
          auth: { user: User };
      }
  }
  

Testing

• Pest/Breeze Tests: Extend AuthenticationTests (unchanged):

  use Laravel\Breeze\Tests\AuthenticationTests;
  
  class CustomAuthTests extends AuthenticationTests {
      protected function getRegistrationData() {
          return [
              'name' => 'Test',
              'email' => 'test@example.com',
              'password' => 'password',
              'password_confirmation' => 'password',
          ];
      }
  }
  

Deployment

• API Stack: Configure CORS in config/cors.php (unchanged):

  'paths' => ['api/*', 'sanctum/csrf-cookie'],
  'allowed_methods' => ['*'],
  'allowed_origins' => ['https://your-app.com'],
  

• Laravel 13+: Ensure bootstrap.js is built and served:

  npm run build
  

Gotchas and Tips

Pitfalls

1. Missing bootstrap.js in Laravel 13+

   • Issue: Inertia/React/Vue stacks fail with bootstrap is not defined.
   • Fix: Create resources/js/bootstrap.js if missing:

     import { createApp, h } from 'vue';
     import { createInertiaApp } from '@inertiajs/vue3';
     createInertiaApp({
         resolve: name => require(`./Pages/${name}.vue`),
         setup({ el, App, props, plugin }) {
             createApp({ render: () => h(App, props) })
                 .use(plugin)
                 .mount(el);
         },
     });
     

   • Note: Fixed in Breeze v2.4.2 but requires manual verification.

2. Middleware Group Conflicts (Laravel 13+)

   • Issue: auth middleware may not work if web middleware is misconfigured.
   • Fix: In app/Http/Kernel.php, ensure:

     'web' => [
         \App\Http\Middleware\EncryptCookies::class,
         \Illuminate\Auth\Middleware\Authenticate::class, // Must come after EncryptCookies
     ],
     

3. Sanctum CSRF Token Missing

   • Issue: 419 Unknown status group in API requests.
   • Fix: Add domains to config/sanctum.php:

     'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', 'localhost,127.0.0.1:3000,your-app.test')),
     

4. Vue/React TypeScript Errors

   • Issue: Property 'auth' does not exist on type 'PageProps'.
   • Fix: Extend types in resources/js/shims-vue.d.ts:

     declare module '@inertiajs/core' {
         interface PageProps {
             auth: { user: User | null };
         }
     }
     

5. Tailwind Dark Mode Persistence

   • Issue: Dark mode resets on page reload.
   • Fix: Use localStorage in app.js: