Filament Jetstream Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require stephenjude/filament-jetstream
   php artisan filament-jetstream:install
   

   • Follow prompts to choose between Livewire or Inertia (recommended for SPAs).
   • Select Team Support if needed (default: disabled).

2. Publish Assets:

   npm install && npm run dev
   

   • Or for production:

     npm run build
     

3. First Use Case:

   • Visit /login to test authentication.
   • Register a user via /register.
   • Access the Filament admin panel at /admin (default credentials: admin@example.com/password).

Key Files to Review

• Configuration: config/filament-jetstream.php (customize branding, auth defaults).
• Providers: App\Providers\FilamentJetstreamServiceProvider.php (extend functionality).
• Views: resources/views/vendor/filament-jetstream/ (override templates).
• Migrations: database/migrations/ (customize user/team tables).

Implementation Patterns

Core Workflows

1. Authentication Flows:

   • Login/Register: Extend FilamentJetstream\Providers\AuthServiceProvider to add custom validation.
   • 2FA: Use FilamentJetstream\TwoFactorAuthenticatable trait for user models.
   • Password Reset: Override FilamentJetstream\PasswordResetService for custom logic.

2. Team Management:

   • Invitations: Extend FilamentJetstream\TeamInvitation model for custom fields.
   • Roles/Permissions: Use Filament’s built-in Policy system or integrate with spatie/laravel-permission.

3. API Tokens:

   • Leverage Filament’s Resource system to list/manage tokens via /admin/personal-access-tokens.

4. Profile Management:

   • Customize FilamentJetstream\Profile resource by publishing views:

     php artisan vendor:publish --tag="filament-jetstream-views"
     

Integration Tips

• Filament Panels:
  • Register custom panels in AppServiceProvider:

    Filament::registerPanel(
        FilamentJetstreamPanel::make()
            ->id('admin')
            ->path('admin')
            ->login()
            ->registration()
            ->passwordReset()
            ->emailVerification()
            ->twoFactorAuthentication()
            ->profileManagement()
            ->teams()
    );
    

• Inertia/React/Vue:
  • Use filament/inertia for SPA integration. Example:

    // resources/js/Pages/Admin/Profile.jsx
    import { Head, router } from '@inertiajs/react';
    import FilamentProfile from 'filament-jetstream/resources/js/Pages/Profile';
    

• Testing:
  • Use FilamentJetstreamTesting trait for auth tests:

    use FilamentJetstream\Testing\FilamentJetstreamTesting;
    
    public function test_login()
    {
        $this->actingAsUser(factory(User::class)->create())
             ->get('/admin')
             ->assertSuccessful();
    }
    

Gotchas and Tips

Pitfalls

1. Asset Conflicts:

   • Ensure filament/support and filament/filament are up-to-date. Run:

     composer update filament/support filament/filament
     

   • Clear cached views:

     php artisan view:clear
     

2. Team Support Quirks:

   • If using teams, ensure App\Models\User uses FilamentJetstream\HasTeams trait.
   • Custom team fields require publishing migrations:

     php artisan vendor:publish --tag="filament-jetstream-migrations"
     

3. 2FA Edge Cases:

   • Test recovery codes thoroughly. Override FilamentJetstream\TwoFactorAuthenticatable to log failed attempts:

     protected function failedTwoFactorAttempt()
     {
         event(new TwoFactorFailed($this));
     }
     

4. Session Management:

   • Avoid manual session handling. Use Filament’s built-in filament/support for auth middleware.

Debugging Tips

• Logs: Enable Filament logs in config/filament.php:

  'logging' => true,
  

• Blade Debugging: Add @debug to Filament views to inspect data:

  @debug(auth()->user())
  

• Database: Use tinker to inspect Jetstream models:

  php artisan tinker
  >>> $user = App\Models\User::first();
  >>> $user->teams
  

Extension Points

1. Custom Fields:

   • Add fields to the Profile resource via service provider:

     FilamentJetstream::profileResource(function (ProfileResource $resource) {
         $resource->addFields([
             TextInput::make('custom_field')->columnSpanFull(),
         ]);
     });
     

2. Notifications:

   • Extend FilamentJetstream\Notifications\TwoFactorAuthenticationNotification for custom emails.

3. API Endpoints:

   • Use Filament’s API Resources to expose Jetstream data:

     Filament::registerApiResources([
         ApiPersonalAccessTokenResource::class,
     ]);
     

4. Dark Mode:

   • Enable in config/filament.php:

     'dark_mode' => true,
     

Pro Tips

• Localization: Publish language files:

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

• Performance: Disable unused features (e.g., teams) in filament-jetstream.php:

  'features' => [
      'teams' => false,
  ],
  

• CI/CD: Add to .github/workflows/tests.yml:

  - run: php artisan test --filter=FilamentJetstreamTests