Starter Kit Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require servicioslineaonce/starter-kit:^1.0 --dev
   

2. Run the installer (interactive mode):

   php artisan kitlauncher:install
   

   • Select your preferred UI preset (PrimeVue, Naive, React, or WireUI).
   • Choose whether to include authentication (--auth).
   • Confirm with --force if overwriting existing files.

3. Post-installation setup:

   composer install
   npm install
   npm run dev
   php artisan migrate
   

First Use Case: Quick Project Scaffolding

Use the package to bootstrap a Laravel project with a modern frontend stack in minutes. Ideal for:

• New projects needing a pre-configured UI (Inertia/Livewire).
• Legacy projects migrating to a structured frontend.
• Teams wanting consistent scaffolding (e.g., PrimeVue + Tailwind).

Example (non-interactive):

php artisan kitlauncher:install --ui=primevue --auth --force --no-interaction

Implementation Patterns

1. Frontend Stack Integration

Inertia (Vue/React) Workflow:

• Page Structure: Use resources/js/Pages/ for Inertia components (e.g., Welcome.vue, Dashboard.vue).
• Layouts: Extend resources/js/Layouts/AppLayout.vue for shared UI (e.g., headers, footers).
• Shared Components: Place reusable components in resources/js/Components/ (e.g., Button.vue, Alert.vue).
• Routing: Leverage Ziggy for Laravel route generation in frontend code.

Example (PrimeVue Inertia):

<!-- resources/js/Pages/Dashboard.vue -->
<script setup>
import AppLayout from '@/Layouts/AppLayout.vue';
import Welcome from '@/Components/Welcome.vue';
</script>

<template>
  <AppLayout>
    <Welcome />
  </AppLayout>
</template>

Livewire (Blade) Workflow:

• Components: Create Livewire components in app/Livewire/ (e.g., Auth/Login.php).
• Blade Templates: Use resources/views/ for Blade layouts (e.g., layouts/app.blade.php).
• WireUI Integration: Extend WireUI components (e.g., <x-wire-button>).

Example (WireUI Livewire):

// app/Livewire/Auth/Login.php
public function mount()
{
    $this->form = [
        'email' => '',
        'password' => '',
    ];
}

<!-- resources/views/auth/login.blade.php -->
<x-wireui.auth.login />

2. Authentication Flow

Key Files:

• Controllers: app/Http/Controllers/Auth/ (e.g., LoginController.php).
• Requests: app/Http/Requests/Auth/ (e.g., LoginRequest.php).
• Middleware: app/Http/Middleware/ (e.g., Authenticate.php, VerifyCsrfToken.php).

Customizing Auth:

1. Extend User Model:

   // app/Models/User.php
   use ServiciosLineaOnce\StarterKit\Traits\TwoFactorAuth;
   class User extends Authenticatable
   {
       use TwoFactorAuth;
   }
   

2. Override Views: Modify resources/views/auth/ (e.g., login.blade.php for Livewire or Login.vue for Inertia).
3. Disable Features:

   SLO_AUTH_REGISTRATION=false
   SLO_AUTH_TWO_FACTOR=false
   

Two-Factor Auth (TOTP):

• Recovery Codes: Generate via /settings/two-factor/recovery-codes.
• QR Setup: Users scan the QR code from /settings/two-factor in their authenticator app.
• Middleware: VerifyTwoFactor protects routes requiring 2FA.

3. Internationalization

Frontend (Inertia):

• Language Switcher: Use the helper in resources/js/lib/i18n.js:

  import { useI18n } from '@/lib/i18n';
  const { locale, setLocale } = useI18n();
  

• Translation Files: Extend lang/es/kit.php or lang/en/kit.php.

Backend:

• Middleware: SetLocale reads from session:

  $locale = session('locale', config('app.locale'));
  

• Route: Update locale via POST /locale/{locale}.

4. Testing

• Auth Tests: Run php artisan test to execute feature tests in tests/Feature/Auth/.
• Custom Tests: Extend tests/Feature/ExampleTest.php for preset-specific assertions.

Gotchas and Tips

Pitfalls

1. Middleware Conflicts:

   • Issue: Installing WireUI after Inertia may leave HandleInertiaRequests in bootstrap/app.php.
   • Fix: Run --force to clean up:

     php artisan kitlauncher:install --ui=wireui --force
     

2. NPM Dependency Conflicts:

   • Issue: Mixing presets (e.g., PrimeVue + React) may cause version clashes.
   • Fix: Use --force to purge old dependencies:

     npm uninstall @primevue/themes @inertiajs/vue3
     npm install
     

3. Migration Conflicts:

   • Issue: Running migrations after switching presets may fail if tables exist.
   • Fix: Reset your database or use --force to overwrite migrations.

4. Vite Config Overwrites:

   • Issue: Custom vite.config.js may be lost during preset changes.
   • Fix: Backup your config before running --force.

Debugging Tips

1. Check Installed Files:

   php artisan kitlauncher:install --dry-run
   

   (View what would be installed without modifying files.)

2. Auth Debugging:

   • Clear Sessions: php artisan session:clear.
   • Check Logs: tail -f storage/logs/laravel.log during auth flows.
   • Test 2FA: Use php artisan tinker to manually verify TOTP:

     $user = \App\Models\User::first();
     $user->generateTwoFactorSecret();
     $user->twoFactorSecret; // Scan this in an authenticator app
     

3. Locale Issues:

   • Verify Middleware: Ensure SetLocale is registered in bootstrap/app.php.
   • Check Session: session()->get('locale') should reflect the current locale.

Extension Points

1. Custom Presets:

   • Add a New Preset: Copy stubs/presets/primevue/ to a new folder (e.g., stubs/presets/myui/).
   • Update Command: Modify InstallCommand.php to include your preset in the --ui options.

2. Override Stubs:

   • Custom Auth Views: Place files in resources/views/auth/ before installation to preserve them.
   • Custom Components: Add to resources/js/Components/; these won’t be overwritten by --force.

3. Configuration:

   • Extend config/servicios-linea-once.php:

     'auth' => [
         'registration' => env('SLO_AUTH_REGISTRATION', false), // Disable registration
         'two_factor' => [
             'required' => true, // Make 2FA mandatory
         ],
     ],
     

4. CI/CD Integration:

   • Non-Interactive Install:

     php artisan kitlauncher:install --ui=react --auth --force --no-interaction
     composer install
     npm ci
     npm run build
     php artisan migrate --force
     

Pro Tips

1. Partial Auth Setup:

   • Install only auth without a UI preset:

     php artisan kitlauncher:install --auth --no-interaction
     

2. Tailwind Customization:

   • Extend resources/css/theme-effects.css for preset-specific styles.

3. Livewire + Inertia Hybrid:

   • Use WireUI for admin panels and Inertia for public pages by manually splitting middleware.

4. Localization Shortcuts:

   • Frontend: Use @lang('kit.welcome') in Blade or {{ __('kit.welcome') }} in Vue/React.
   • Backend: Inject locale into controllers:

     use Illuminate\Support\Facades\App;
     App::setLocale($request->session()->get('locale'));
     

5. Performance:

   • Lazy-Load Presets: For large apps, split resources/js/app.js into chunks using Vite’s build.rollupOptions.
   • Cache Views: Enable Blade caching (php artisan view:cache) for Livewire presets.