Kui Laravel Jetstream Laravel Package

Getting Started

Minimal Steps to Begin

1. Prerequisites Check Ensure your Laravel project meets requirements:

   • Laravel ≥ 8.0
   • Jetstream installed (php artisan jetstream:install livewire --teams)
   • Vite or Laravel Mix configured (package auto-detects this).

2. Installation

   composer require kamona/kui-laravel-jetstream --dev
   php artisan kui:install
   

   The kui:install command replaces Jetstream’s default UI with K UI’s theme while preserving functionality.

3. First Use Case

   • Visit /dashboard or /login to see the new UI.
   • No additional configuration is needed for basic auth/teams features (e.g., profile updates, team management).

Where to Look First

• Published Assets: Check resources/views/vendor/kui/ for customizable Blade templates.
• Configuration: Review config/kui.php for theme options (e.g., colors, logo).
• Documentation: Refer to the Jetstream docs for feature-specific guidance (e.g., two-factor auth).

Implementation Patterns

Core Workflows

1. Theme Customization

   • Override K UI’s views by publishing assets:

     php artisan vendor:publish --tag=kui-views
     

   • Modify files in resources/views/vendor/kui/ (e.g., auth/login.blade.php).
   • Tip: Use @extends('kui::layouts.app') in custom views to inherit K UI’s layout.

2. Integration with Jetstream Features

   • Teams: Leverage K UI’s team management UI out-of-the-box (e.g., /teams routes).
   • Two-Factor Auth: Use K UI’s TOTP/backup code UI via Jetstream’s TwoFactorAuthenticated middleware.
   • API Tokens: Access the /user/tokens page for token management.

3. Asset Management

   • Vite/Laravel Mix: K UI works with both. For Vite, ensure vite.config.js includes:

     import { defineConfig } from 'vite';
     import laravel from 'laravel-vite-plugin';
     
     export default defineConfig({
       plugins: [
         laravel({
           input: ['resources/css/app.css', 'resources/js/app.js'],
           refresh: true,
         }),
       ],
     });
     

   • CSS/JS: K UI’s assets are auto-loaded via Jetstream’s stack. Add custom styles to resources/css/app.css.

4. Localization

   • Publish language files:

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

   • Modify resources/lang/{locale}/kui.php for translations.

Advanced Patterns

• Dynamic Theming: Use config/kui.php to toggle themes (e.g., theme: 'dark').
• Custom Routes: Extend K UI’s routes by adding middleware to Jetstream’s routes/web.php:

  Route::middleware(['auth:sanctum', 'verified'])->group(function () {
      Route::get('/custom-page', [CustomController::class, 'index'])
           ->name('custom.page');
  });
  

• Livewire Components: K UI replaces Jetstream’s Livewire components (e.g., Profile). Extend them by creating new Livewire components in app/Http/Livewire/ and referencing them in K UI’s views.

Gotchas and Tips

Pitfalls

1. Asset Conflicts

   • Issue: K UI’s CSS/JS may conflict with custom assets if not properly scoped.
   • Fix: Use unique class names or inspect the published assets (resources/views/vendor/kui/) to avoid overrides.

2. Middleware Mismatches

   • Issue: Jetstream’s auth middleware (e.g., verified) may not align with K UI’s routes.
   • Fix: Verify routes in routes/web.php and ensure middleware matches Jetstream’s defaults.

3. Team Feature Gaps

   • Issue: K UI’s team UI may lack specific features (e.g., custom team fields).
   • Fix: Extend the Team model or create custom Livewire components for additional fields.

4. Vite/HMR Issues

   • Issue: Hot Module Replacement (HMR) may not work if K UI’s assets aren’t properly linked.
   • Fix: Ensure resources/js/app.js imports K UI’s JS (if applicable) and check Vite’s input paths.

Debugging Tips

• View Overrides: Use php artisan view:clear after modifying K UI’s published views.
• Asset Compilation: Run npm run dev or npm run build to refresh assets.
• Route Debugging: Use php artisan route:list to verify K UI’s routes are registered.
• Livewire Debugging: Check Livewire logs (storage/logs/livewire.log) for component errors.

Configuration Quirks

1. Theme Switching

   • K UI supports dynamic themes via config/kui.php. Test changes by toggling the theme key and clearing the view cache.

2. Logo/Colors

   • Customize config/kui.php:

     'logo' => 'path/to/logo.svg',
     'colors' => [
         'primary' => '#3b82f6',
         'secondary' => '#10b981',
     ],
     

   • Note: Some colors may require additional CSS overrides in app.css.

3. Dark Mode

   • Enable via config/kui.php:

     'dark_mode' => true,
     

   • Tip: Test dark mode on mobile devices to ensure proper contrast.

Extension Points

1. Custom Components

   • Extend K UI’s Livewire components by creating new components in app/Http/Livewire/ and referencing them in K UI’s views (e.g., @livewire('custom.component')).

2. API Endpoints

   • K UI relies on Jetstream’s API routes (e.g., /api/user). Extend these via Jetstream’s Fortify or Sanctum services.

3. Notifications

   • Customize notifications by publishing K UI’s assets and modifying resources/views/vendor/kui/notifications/.

4. Database Seeding

   • Seed users/teams with K UI-compatible data:

     User::factory()->create([
         'name' => 'Test User',
         'email' => 'test@example.com',
     ]);