Ui Laravel Package

Getting Started

Minimal Steps

1. Install the package:

   composer require laravel/ui
   

2. Generate scaffolding (choose one):
   • Bootstrap (basic):

     php artisan ui bootstrap
     

   • Vue (with auth):

     php artisan ui vue --auth
     

   • React (with auth):

     php artisan ui react --auth
     

3. Install frontend dependencies:

   npm install
   

4. Compile assets (Vite):

   npm run dev
   

5. Run migrations (if using auth scaffolding):

   php artisan migrate
   

First Use Case

Scaffold a Vue.js + Bootstrap authentication system:

php artisan ui vue --auth
npm install && npm run dev
php artisan migrate

This generates:

• Blade auth views (/resources/views/auth/)
• Vue components (/resources/js/components/)
• Vite config (/vite.config.js)
• SASS setup (/resources/sass/app.scss)

Implementation Patterns

Core Workflows

1. Authentication Scaffolding

• Pattern: Use --auth flag to generate login/registration flows.
• Files affected:
  • Blade views (login.blade.php, register.blade.php)
  • Vue/React components (e.g., Login.vue)
  • Routes (/routes/web.php)
  • Controllers (Auth/LoginController.php)
• Customization:
  • Override Blade views in /resources/views/auth/.
  • Extend Vue components in /resources/js/components/.

2. Frontend Integration

• Vite + SASS:
  • Customize /resources/sass/app.scss (import Bootstrap variables, add custom styles).
  • Extend /resources/js/app.js for global JS setup (e.g., Axios defaults, Vue plugins).
• Component Registration:
  • Register Vue components in app.js:

    import Welcome from './components/Welcome.vue';
    Vue.component('welcome', Welcome);
    

  • Use in Blade:

    <welcome></welcome>
    

3. Preset Extensions

• Add a custom preset (e.g., alpinejs):

  // In AppServiceProvider@boot()
  Laravel\Ui\UiCommand::macro('alpinejs', function ($command) {
      $command->scaffold([
          'vite' => ['@alpinejs/vue' => '^3.0'],
          'js' => 'resources/js/app.js',
          'views' => ['auth' => 'resources/views/auth'],
      ]);
  });
  

  Run with:

  php artisan ui alpinejs
  

4. Asset Management

• Development:

  npm run dev       # Single build
  npm run watch     # Auto-reload on changes
  

• Production:

  npm run build     # Optimized assets
  

• Vite Hot Module Replacement (HMR): Configure vite.config.js for HMR:

  export default defineConfig({
      server: {
          hmr: {
              host: 'localhost',
              port: 3000,
          },
      },
  });
  

Integration Tips

Laravel Mix → Vite Migration

• Replace mix-manifest.json references with Vite’s @vite() directive:

  @vite(['resources/sass/app.scss', 'resources/js/app.js'])
  

• Update webpack.mix.js (if used) to Vite config.

Authentication Logic

• Customize Auth Controllers: Extend Auth/LoginController to add logic (e.g., 2FA):

  public function __construct() {
      $this->middleware('throttle:5,1')->only('login');
      $this->middleware('2fa.verified')->except('show2FAForm');
  }
  

• Session Handling: Use auth()->user() in Blade/Vue:

  // Vue example
  export default {
      data() {
          return {
              user: @json(auth()->user())
          };
      },
  };
  

API Routes

• Pair with Laravel Sanctum/Passport for SPA auth:

  composer require laravel/sanctum
  php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
  

• Configure CORS in config/cors.php:

  'paths' => ['api/*', 'sanctum/csrf-cookie'],
  

Gotchas and Tips

Pitfalls

1. Vite Configuration Conflicts:

   • Issue: @vitejs/plugin-vue conflicts with Laravel 12+.
   • Fix: Update vite.config.js:

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

   • Reference: PR #279.

2. Bootstrap Version Mismatches:

   • Issue: Newer Bootstrap (v5+) breaks older Laravel UI templates.
   • Fix: Update package.json:

     "bootstrap": "^5.3.0",
     "popper.js": "^2.11.6"
     

   • Run npm install && npm run dev.

3. Vue/React Component Registration:

   • Issue: Components not rendering due to incorrect registration.
   • Debug:
     • Check app.js for proper imports/registration.
     • Verify Blade template has the correct component tag (case-sensitive).

4. Auth Middleware Bypass:

   • Issue: Logout routes failing with "User not authenticated".
   • Fix: Ensure middleware is applied in routes/web.php:

     Route::post('/logout', [LoginController::class, 'logout'])->middleware('auth');
     

5. Vite HMR Not Working:

   • Issue: Changes not reflecting in browser.
   • Fix:
     • Ensure npm run dev is running.
     • Check vite.config.js for correct server.hmr settings.
     • Clear browser cache or use incognito mode.

Debugging Tips

• Asset Compilation Errors:

  • Check npm run dev output for errors.
  • Verify node_modules is intact (npm install if corrupted).
  • Clear Vite cache:

    npm run dev -- --clear
    

• Vue/React Console Errors:

  • Open browser dev tools (F12) to inspect JS errors.
  • Common issues:
    • Missing dependencies (e.g., vue or react not installed).
    • Incorrect component names (case-sensitive).

• Blade Template Issues:

  • Use @dd() to debug variables:

    @dd(auth()->user())
    

  • Check for syntax errors in Blade files.

Configuration Quirks

1. Vite Public Path:

   • Default: /public/build/assets.
   • Customize in vite.config.js:

     export default defineConfig({
         base: '/custom-path/',
     });
     

2. SASS Variables:

   • Override Bootstrap variables in /resources/sass/app.scss:

     $primary: #6c63ff;
     @import "bootstrap/scss/bootstrap";
     

3. Laravel Mix Legacy:

   • If migrating from Mix, update webpack.mix.js to Vite:

     // Remove webpack.mix.js entirely; use vite.config.js instead.
     

Extension Points

1. Custom Auth Views:

   • Override default views in /resources/views/auth/:

     /resources/views/auth/
         ├── login.blade.php
         ├── register.blade.php
         └── verify.blade.php
     

2. Dynamic Presets:

   • Extend UiCommand in a service provider:

     // app/Providers/AppServiceProvider.php
     public function boot() {
         UiCommand::macro('tailwind', function ($command) {
             $command->scaffold([
                 'vite' => ['@tailwindcss/vite' => '^3.0'],
                 'js' => 'resources/js/app.js',
                 'css' => 'resources/css/app.css',
             ]);
         });
     }
     

3. API-First Auth:

   • Replace Blade auth with API endpoints:
     • Remove Blade routes from web.php.
     • Add API routes to api.php:

       Route::post('/login', [LoginController::class, 'login']);
       

     • Use Sanctum for token-based auth.

4. Multi-Frontend Support:

   • Use Vite’s build.manifest to serve multiple entry points:

     // vite.config.js
     export default defineConfig({
         build: {
             rollup