Getting Started

Minimal Steps to Begin

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 server-rendered or inertia for SPA (Vue/React) workflows.

First Use Case:
- Livewire: Visit /register to test the registration flow, then /dashboard to interact with the pre-built profile/team management UI.
- Inertia: Run npm run dev and visit /login to test the SPA-based auth flow.
Key Directories:
- Livewire: app/Http/Livewire (e.g., ManageAccountSettings, DeleteUser).
- Inertia: resources/js/Pages (e.g., Dashboard.vue, Profile/UpdateProfileInformation.vue).
- Blade: resources/views/layouts (shared layouts like app.blade.php).
- Migrations: database/migrations/ (user/team tables).
First Customization:
- Override a Livewire component by copying app/Http/Livewire/ManageAccountSettings.php to your app and modifying it.
- Extend a Vue component by copying resources/js/Pages/Profile/UpdateProfileInformation.vue and customizing the template/data.

Implementation Patterns

Core Workflows

1. Authentication & Authorization

Login/Registration: Jetstream handles sessions, password resets, and email verification out-of-the-box. Extend by publishing views:
```
php artisan vendor:publish --tag=jetstream-views
```
Modify resources/views/auth/ files (e.g., login.blade.php).
Two-Factor Auth (2FA): Enable via php artisan jetstream:install (select "2FA"). Customize the recovery codes view at resources/views/livewire/two-factor-recovery-codes.blade.php.

Middleware: Jetstream registers auth and verified middleware. Add custom middleware to app/Http/Kernel.php:

'web' => [
    \App\Http\Middleware\VerifyCsrfToken::class,
    \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
    \Illuminate\Session\Middleware\AuthenticateSession::class,
    \Illuminate\View\Middleware\ShareErrorsFromSession::class,
    \App\Http\Middleware\Authenticate::class,
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
    \Laravel\Jetstream\Http\Middleware\VerifyCsrfToken::class, // Jetstream-specific CSRF
],

2. Profile & Team Management

Profile Updates: Use the ManageAccountSettings Livewire component or UpdateProfileInformation Inertia page. Extend by overriding the form logic:

// app/Http/Livewire/ManageAccountSettings.php
public function updateProfileInformation()
{
    $this->validate([
        'photo' => ['nullable', 'image'],
        'name' => ['required', 'string', 'max:255'],
    ]);
    // Custom logic here
}

Teams: Jetstream includes team creation/invitation. Customize team roles by extending the Team model or modifying the InviteTeamMembers Livewire component.

3. API Integration (Optional)

Jetstream installs an API stack by default (if selected during installation). Use it for mobile apps or SPAs:

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

Extend the API by adding routes to routes/api.php or customizing the Sanctum auth guard in config/auth.php.

4. Theming & UI

Tailwind CSS: Jetstream uses Tailwind for styling. Override variables in tailwind.config.js or extend the base styles in resources/css/app.css.
Dark Mode: Toggle dark mode via the DarkMode Livewire component (or Inertia equivalent). Customize the toggle button in resources/views/components/dark-mode-toggle.blade.php.
Layouts: Shared layouts are in resources/views/layouts. Extend by copying and modifying (e.g., app.blade.php).

5. Testing

Jetstream includes Pest tests. Run tests with:
```
php artisan test
```

Test authentication flows:

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

Test Livewire components:

$this->livewire(ManageAccountSettings::class)->assertSee('Profile Settings');

Integration Tips

Livewire + Inertia Hybrid: Use Livewire for complex server-side interactions (e.g., file uploads) and Inertia for SPA-like routing. Example:

<!-- resources/js/Pages/Dashboard.vue -->
<template>
    <AppLayout>
        <LivewireManageAccountSettings />
    </AppLayout>
</template>

Custom Validation: Extend Jetstream’s form requests. Publish and modify:
```
php artisan vendor:publish --tag=jetstream-form-requests
```
Then override app/Http/Requests/UpdateProfileInformationRequest.php.

Event Listeners: Listen to Jetstream events (e.g., Registered, ProfileUpdated) in EventServiceProvider:

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

Seeding: Use Jetstream’s factories to seed users/teams:

// database/seeders/DatabaseSeeder.php
$user = User::factory()->create();
$team = Team::factory()->create(['user_id' => $user->id]);

Localization: Publish language files:
```
php artisan vendor:publish --tag=jetstream-lang
```
Then extend resources/lang/en/ or add new locales.

Gotchas and Tips

Pitfalls

Middleware Registration:
- Issue: Jetstream’s VerifyCsrfToken middleware may conflict with Laravel’s default if not ordered correctly in Kernel.php.
- Fix: Ensure Jetstream’s middleware is registered after Laravel’s default VerifyCsrfToken:
```
'web' => [
    // ... other middleware
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
    \Laravel\Jetstream\Http\Middleware\VerifyCsrfToken::class, // Must come after SubstituteBindings
],
```
Inertia vs. Livewire Routes:
- Issue: Mixing Inertia and Livewire routes can cause conflicts if not namespaced properly.
- Fix: Prefix Inertia routes with inertia. in routes/web.php:
```
Route::inertia('/dashboard', 'Dashboard')->middleware(['auth', 'verified']);
```
Team Ownership:
- Issue: Jetstream’s team ownership logic assumes a user_id foreign key. Customizing this requires updating migrations and models.
- Fix: Override the Team model’s user() relationship or publish and modify migrations:
```
php artisan vendor:publish --tag=jetstream-migrations
```
Two-Factor Auth Quirks:
- Issue: Recovery codes may not persist after migration if the two_factor_recovery_codes table isn’t created.
- Fix: Run migrations after enabling 2FA:
```
php artisan migrate
```
Livewire Component Registration:
- Issue: Livewire components may fail to register if the HandleInertiaRequests middleware is misconfigured.
- Fix: Ensure ShareRequestsWithView middleware is registered in Kernel.php:
```
\Laravel\Jetstream\Http\Middleware\ShareRequestsWithView::class,
```

Vite Asset Conflicts:

Issue: Custom Vite plugins may conflict with Jetstream’s default setup.

Fix: Merge Vite configs in vite.config.js:

import laravel from 'laravel-vite-plugin';
import { defineConfig } from 'vite';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
        // Your custom plugins
    ],
});

Database Migrations:
- Issue: Running php artisan migrate after Jetstream installation may fail if the users table already exists.
- Fix: Use --force or manually resolve conflicts:
```
php artisan migrate --force
```

Jetstream Laravel Package