Jetstream Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Run composer require laravel/jetstream in a fresh Laravel 11.x project. Use the installer: php artisan jetstream:install livewire (or inertia for Inertia.js). This sets up:

   • Authentication scaffolding (users, sessions, passwords)
   • Team support (optional)
   • Profile management (photos, passwords, 2FA)
   • Email verification
   • API token management (if enabled)

2. First Use Case

   • User Registration: Navigate to /register to test the registration flow.
   • Login: Use /login to authenticate.
   • Profile Management: Visit /profile to update user details, upload a profile photo, or enable 2FA.

3. Where to Look First

   • Core Files:
     • app/Http/Controllers/Auth/ (Auth logic)
     • app/Models/ (User, Team models)
     • resources/views/ (Blade templates for Livewire/Inertia)
     • resources/js/Pages/ (Inertia.js pages, if using Inertia)
   • Configuration: config/jetstream.php (customize features like teams, 2FA, or API tokens).
   • Migrations: database/migrations/ (user, team, and session tables).

Implementation Patterns

Common Workflows

1. Customizing Authentication Logic

• Extend Forms: Override Livewire/Inertia forms in app/Http/Livewire/ or resources/js/Pages/Auth/. Example: Extend CreateUserForm to add custom validation:

  // app/Http/Livewire/Auth/CreateUserForm.php
  public function rules()
  {
      return array_merge(parent::rules(), [
          'custom_field' => 'required|string',
      ]);
  }
  

• Modify Controllers: Extend app/Http/Controllers/Auth/RegisteredUserController for custom registration logic.

2. Team Management

• Invitations: Use Team::inviteUser() to send invites. Customize the invite logic in app/Actions/Jetstream/InviteTeamMember.php.
• Roles: Assign roles via team->assignRoleToMember($user, 'admin'). Extend app/Models/Team.php to add custom roles.
• Middleware: Protect team routes with canJoinTeam or mustBelongToTeam middleware (defined in app/Http/Middleware/).

3. Profile Customization

• Profile Photos: Use app/Models/User::profilePhotoUrl() to customize photo paths. Override the accessor:

  public function profilePhotoUrl()
  {
      return 'custom/path/' . $this->profile_photo_path;
  }
  

• Additional Profile Fields: Add fields to app/Models/User and update:
  • app/Http/Livewire/Profile/UpdateProfileInformationForm.php
  • resources/js/Pages/Profile/UpdateProfileInformation.vue (Inertia).

4. API Integration

• API Tokens: Enable tokens in config/jetstream.php ('features' => ['api' => true]). Use user->createToken() to generate tokens.
• Sanctum/Passport: Jetstream integrates with Sanctum by default. Extend app/Http/Controllers/Auth/Sanctum/AuthenticatedSessionController for custom API logic.

5. Email Customization

• Templates: Override email templates in resources/views/vendor/jetstream/.
• Mailables: Extend app/Mail/ to customize verification/notification emails.

6. Testing

• Factories: Use User::factory() or Team::factory() in tests.
• Test Helpers: Leverage actingAs() for authentication and followRedirects() for testing flows:

  $user = User::factory()->create();
  $response = $this->actingAs($user)->get('/profile');
  

Integration Tips

• Livewire: Register custom Livewire components in app/Providers/AppServiceProvider:

  public function boot()
  {
      Livewire::component('custom-component', \App\Livewire\CustomComponent::class);
  }
  

• Inertia.js: Extend Inertia pages in resources/js/Pages/. Use useForm for reactive forms:

  <script setup>
  import { useForm } from '@inertiajs/inertia-vue3';
  const form = useForm({ ... });
  </script>
  

• Middleware: Add custom middleware to app/Http/Kernel.php under the web group:

  'web' => [
      \App\Http\Middleware\CustomMiddleware::class,
      // ...
  ],
  

• Policies: Define policies in app/Policies/ to restrict access (e.g., UserPolicy, TeamPolicy).

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • Issue: Running php artisan migrate after Jetstream installation may fail if custom migrations exist for users or teams tables.
   • Fix: Use php artisan jetstream:install --migrate to handle migrations safely or manually merge migration files.

2. Livewire/Inertia Incompatibility

   • Issue: Mixing Livewire and Inertia components without proper isolation can cause state conflicts.
   • Fix: Use Inertia’s Inertia.render() for Livewire components or vice versa sparingly. Prefer one stack per project.

3. Team Ownership Logic

   • Issue: Teams require at least one owner. Deleting the last owner breaks team functionality.
   • Fix: Add validation in app/Actions/Jetstream/DeleteTeam.php:

     public function handle()
     {
         if ($this->team->members()->count() <= 1) {
             throw ValidationException::withMessages(['team' => ['Cannot delete the last team owner.']]);
         }
         // ...
     }
     

4. Session Handling

   • Issue: Custom session drivers may not work out-of-the-box with Jetstream’s session-based features (e.g., 2FA).
   • Fix: Configure config/session.php to use database or file drivers and ensure SESSION_DRIVER is set in .env.

5. Two-Factor Authentication (2FA)

   • Issue: 2FA recovery codes may not persist after database migrations.
   • Fix: Run php artisan jetstream:recover-2fa to regenerate recovery codes for existing users.

6. API Token Scopes

   • Issue: Sanctum tokens lack custom scopes by default.
   • Fix: Extend app/Models/User and override tokens():

     public function tokens()
     {
         return $this->hasMany(\Laravel\Sanctum\PersonalAccessToken::class)->addSelect(['id', 'tokenable_id', 'tokenable_type', 'name', 'abilities', 'created_at', 'updated_at']);
     }
     

Debugging Tips

1. Livewire Debugging

   • Use php artisan livewire:discover to refresh components.
   • Check storage/logs/livewire.log for component errors.

2. Inertia Debugging

   • Enable Inertia debug mode in resources/js/app.js:

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

   • Check browser console for Inertia errors (e.g., 419 errors due to CSRF).

3. Team Invitation Issues

   • Verify team_invitations table exists and invitable trait is added to User model.
   • Check config/jetstream.php for team_invitations table name.

4. Profile Photo Uploads

   • Ensure public/storage/app/public is symlinked to storage/app/public:

     php artisan storage:link
     

   • Verify filesystem.php config for public disk:

     'public' => [
         'driver' => 'local',
         'root' => storage_path('app/public'),
         'url' => env('APP_URL').'/storage',
         'visibility' => 'public',
     ],
     

Extension Points

1. Custom Features

   • Add Social Logins: Extend app/Http/Controllers/Auth/SocialiteController and update config/auth.php.
   • Custom Roles: Replace app/Models/Team role logic with a middleware-based system (e.g., app/Http/Middleware/CheckTeamRole.php).

2. Theming

   • Override Tailwind classes in resources/css/app.css