Jetstream Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation:

   composer require laravel/jetstream
   php artisan jetstream:install livewire  # or inertia for SPA
   npm install && npm run dev
   php artisan migrate
   

   • Choose livewire for traditional server-rendered apps or inertia for modern SPAs.

2. First Use Case:

   • Access /register and /login routes to test authentication.
   • Navigate to /dashboard to see the pre-built UI (profile management, teams, etc.).

3. Key Directories:

   • Auth: app/Http/Controllers/Auth/ (Livewire/Inertia controllers).
   • Views: resources/views/ (Blade) or resources/js/Pages/ (Inertia/Vue).
   • Models: app/Models/ (User, Team, etc.).
   • Policies: app/Policies/ (Authorization logic).

4. First Customization:

   • Override a view (e.g., resources/views/auth/login.blade.php).
   • Extend a Livewire component (e.g., app/Http/Livewire/UpdateProfileInformation.php).

Implementation Patterns

Core Workflows

1. Authentication & Sessions

• Login/Registration: Use Jetstream’s built-in controllers (LoginController, RegisterController) or extend them. Example: Custom validation in app/Http/Controllers/Auth/RegisteredUserController.php.
• Session Handling: Leverage auth() helper or AuthenticatesUsers trait. Jetstream includes session management for "remember me" and SSO.

// Extend registration logic
public function register(Request $request) {
    $request->validate([
        'name' => 'required|string|max:255',
        'email' => 'required|string|email|max:255|unique:users',
        'password' => ['required', 'confirmed', 'min:8'],
        'terms' => 'accepted', // Custom rule
    ]);
    // ...
}

2. Profile Management

• Livewire Components: Extend UpdateProfileInformation or DeleteUser for custom logic. Example: Add a "bio" field to UpdateProfileInformation.php:

  public $bio;
  protected $rules = [
      'bio' => 'nullable|string|max:500',
  ];
  

• Inertia Forms: Modify UpdateProfileInformationForm.vue to include new fields.

3. Teams & Collaboration

• Team Creation/Invitation: Use CreateTeam Livewire component or InviteTeamMember for team-based workflows. Example: Customize team roles in app/Models/Team.php:

  public function addMember(User $user, $role = 'member') {
      $this->members()->attach($user->id, ['role' => $role]);
  }
  

• Team Policies: Extend TeamPolicy to define custom permissions:

  public function delete(Team $team, User $user) {
      return $user->id === $team->owner_id;
  }
  

4. Two-Factor Authentication (2FA)

• Enable/Disable: Use EnableTwoFactorAuthentication Livewire component. Customize recovery codes in app/Models/User.php:

  public function recoveryCodes(): HasMany {
      return $this->hasMany(RecoveryCode::class);
  }
  

• Backup Codes: Extend ShowTwoFactorAuthenticationForm to add custom backup logic.

5. API Integration (Optional)

• Sanctum/Passport: Jetstream includes API scaffolding. Extend app/Http/Controllers/API/ controllers. Example: Add a custom API endpoint:

  Route::middleware('auth:sanctum')->get('/user/profile', function (Request $request) {
      return response()->json($request->user()->profile);
  });
  

6. Testing

• Pest/Laravel Tests: Use Jetstream’s test helpers (e.g., actingAs, createUser). Example:

  use Laravel\Jetstream\Tests\TestCase;
  
  public function test_profile_update() {
      $user = User::factory()->create();
      actingAs($user);
      $response = put('/user/profile-information', [
          'name' => 'New Name',
      ]);
      $response->assertRedirect('/dashboard');
  }
  

Integration Tips

1. Tailwind CSS:

   • Customize tailwind.config.js to extend Jetstream’s theme. Example:

     module.exports = {
         theme: {
             extend: {
                 colors: {
                     primary: '#10B981', // Custom primary color
                 },
             },
         },
     };
     

   • Override styles in resources/css/app.css.

2. Localization:

   • Publish Jetstream’s language files:

     php artisan vendor:publish --tag=jetstream-lang
     

   • Customize translations in resources/lang/.

3. Notifications:

   • Extend app/Notifications/ to create custom notifications (e.g., TeamInvitation).
   • Use Jetstream’s Notification facade:

     Notification::route('mail', $user->email)
                 ->notify(new TeamInvitation($team));
     

4. Event Handling:

   • Listen to Jetstream events (e.g., Registered, TeamCreated) in EventServiceProvider:

     protected $listen = [
         'Laravel\Jetstream\Events\Registered' => [
             'App\Listeners\LogNewUser',
         ],
     ];
     

5. Middleware:

   • Add custom middleware to app/Http/Kernel.php:

     protected $middlewareGroups = [
         'web' => [
             \App\Http\Middleware\VerifyCustomCSP::class,
             // ...
         ],
     ];
     

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • Issue: Running php artisan migrate after installing Jetstream may fail if you’ve modified users or teams tables.
   • Fix: Reset migrations or manually merge changes:

     php artisan migrate:fresh --seed
     

   • Tip: Use --pretend to preview changes:

     php artisan migrate --pretend
     

2. Livewire/Inertia Mismatch:

   • Issue: Mixing Livewire and Inertia components can cause routing conflicts.
   • Fix: Stick to one stack per project. If switching, run:

     php artisan jetstream:install inertia  # or livewire
     

3. Team Ownership Logic:

   • Issue: Custom team logic may break ownership checks (e.g., owner_id).
   • Fix: Override TeamPolicy or use accessors:

     public function isOwner(User $user) {
         return $user->id === $this->owner_id;
     }
     

4. 2FA Recovery Codes:

   • Issue: Recovery codes may not regenerate after deletion.
   • Fix: Clear and regenerate codes in app/Models/User.php:

     public function generateRecoveryCodes() {
         $this->recoveryCodes()->delete();
         RecoveryCode::generateFor($this);
     }
     

5. Session Timeout:

   • Issue: Jetstream’s session driver may not match your config/session.php.
   • Fix: Ensure driver is set to file, database, or redis:

     'driver' => env('SESSION_DRIVER', 'file'),
     

6. Vite Asset Loading:

   • Issue: Assets fail to load after customizing vite.config.js.
   • Fix: Rebuild assets:

     npm run build
     

   • Tip: Use php artisan vite:build for production.

7. Inertia Page Titles:

   • Issue: Page titles don’t update dynamically.
   • Fix: Use Inertia’s title prop in Vue components:

     <template>
         <Head title="Custom Title" />
     </template>
     

Debugging Tips

1. Livewire Debugging:

   • Enable Livewire logging:

     'livewire' => [
         'log' => env('APP_DEBUG', false),
     ],
     

   • Check storage/logs/livewire.log.

2. Inertia Debugging:

   • Use Inertia::debug() in middleware to inspect page props:

     public function handle(Request $request, Closure $next) {
         if (app()->environment('local')) {
             Inertia::debug(fn ($view) => [
                 'url' => $view['url'],
                 'props' => $view['props'],
             ]);
         }
         return $next($request);
     }
     

3. Team Invitation Issues: