Ui Laravel Package

## Getting Started

### Minimal Setup
1. **Install the package**:
   ```bash
   composer require laravel/ui

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

     php artisan ui bootstrap
     

   • Vue with auth:

     php artisan ui vue --auth
     

   • React with auth:

     php artisan ui react --auth
     

3. Install NPM dependencies:

   npm install
   

4. Compile assets (Vite):

   npm run dev
   

5. Publish assets (for production):

   npm run build
   

First Use Case

• Quick auth scaffolding: Use php artisan ui vue --auth to generate login, registration, password reset, and email verification views, controllers, and routes.
• Customize Blade templates: Edit files in resources/views/auth/ (e.g., login.blade.php) to modify forms, validation messages, or styling.

Implementation Patterns

Workflows

1. Authentication Flow:

   • Use AuthenticatesUsers trait in controllers (e.g., LoginController).
   • Customize login logic in handleUserLogin() or override validateLogin().
   • Extend RegistersUsers for registration (e.g., add custom validation in validator()).

2. Frontend Integration:

   • Vue/React: Register components in resources/js/app.js:

     import ExampleComponent from './components/ExampleComponent.vue';
     Vue.component('example-component', ExampleComponent);
     

   • Blade: Embed components in views:

     <example-component :data="{{ json_encode($data) }}"></example-component>
     

   • API Calls: Use Axios (included by default) for frontend-backend communication:

     axios.post('/login', { email, password })
       .then(response => { /* handle */ });
     

3. Asset Management:

   • Vite: Configure in vite.config.js to customize entry points or plugins.
   • SASS: Override Bootstrap variables in resources/sass/app.scss:

     $primary: #3490dc;
     @import "bootstrap/scss/bootstrap";
     

   • JavaScript: Split logic into modular files (e.g., resources/js/auth.js) and import into app.js.

4. Customization:

   • Views: Override default Blade templates in resources/views/auth/ or resources/views/layouts/.
   • Routes: Extend routes/web.php to add custom routes for auth middleware:

     Route::middleware(['auth'])->group(function () {
         Route::get('/dashboard', [DashboardController::class, 'index']);
     });
     

5. Testing:

   • Use actingAs() in tests:

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

   • Test frontend interactions with Laravel Dusk or Cypress.

Gotchas and Tips

Pitfalls

1. Asset Compilation:

   • Issue: npm run dev fails with missing dependencies. Fix: Run npm install first or check package.json for version conflicts.
   • Issue: Vite hot-reload not working. Fix: Ensure vite.config.js includes the correct entry points and run npm run dev -- --host for external access.

2. Authentication:

   • Issue: AuthenticatesUsers forces "remember me" by default. Fix: Override validateLogin() to exclude the remember field:

     protected function validateLogin(Request $request) {
         return $request->validate([
             'email' => 'required|email',
             'password' => 'required',
             // Remove 'remember' from validation
         ]);
     }
     

   • Issue: Password confirmation fails silently. Fix: Check password_confirmed_at in the users table or update ConfirmsPasswords trait.

3. Frontend:

   • Issue: Vue/React components not rendering. Fix: Verify components are registered in app.js and imported correctly. Debug: Check browser console for errors (e.g., missing dependencies).
   • Issue: Bootstrap styles not applied. Fix: Ensure app.scss imports Bootstrap correctly and compile assets.

4. Configuration:

   • Issue: ui command not found. Fix: Ensure Laravel\Ui\UiServiceProvider is registered in config/app.php under providers.
   • Issue: Custom presets not working. Fix: Register macros in a service provider before the UiCommand is used:

     UiCommand::macro('nextjs', function () {
         // Scaffold logic
     });
     

Tips

1. Performance:

   • Use npm run build for production to minify assets.
   • Lazy-load non-critical JavaScript (e.g., analytics) with Vite’s dynamic imports:

     const { default: Analytics } = await import('./analytics.js');
     

2. Extensibility:

   • Custom Auth: Create a new trait by extending AuthenticatesUsers:

     trait CustomAuthenticatesUsers {
         use AuthenticatesUsers {
             login as private parentLogin;
         }
         public function login(Request $request) {
             // Custom logic
             $this->parentLogin($request);
         }
     }
     

   • Presets: Extend UiCommand for reusable scaffolding (e.g., php artisan ui tailwind).

3. Debugging:

   • Blade: Use @debug directive to inspect variables:

     @debug($user)
     

   • JavaScript: Log component props in created() lifecycle hook:

     created() {
         console.log('Props:', this.$props);
     }
     

   • Routes: Dump routes with:

     php artisan route:list
     

4. Versioning:

   • Bootstrap: Update package.json to pin Bootstrap versions (e.g., "bootstrap": "^5.3.0") to avoid breaking changes.
   • Laravel: Test UI presets against multiple Laravel versions (e.g., 10.x, 11.x) using laravel/ui's supported versions table.

5. Security:

   • CSRF: Ensure all forms include @csrf:

     <form method="POST" action="/login">
         @csrf
         <!-- fields -->
     </form>
     

   • Passwords: Use Laravel’s Hash::make() and never store plaintext passwords.

6. Legacy Code:

   • Migrate from UI to Breeze/Jetstream: Replace AuthenticatesUsers with LoginController from Breeze and update Blade templates incrementally.
   • Mix to Vite: Update webpack.mix.js to vite.config.js by following Laravel’s migration guide.

---