Ui Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require laravel/ui
   

   • Ensures the package is available for scaffolding.

2. Generate Basic Scaffolding:

   php artisan ui bootstrap
   

   • Creates a basic Bootstrap setup with Vite for asset compilation.

3. Install Dependencies:

   npm install && npm run dev
   

   • Installs Node dependencies and compiles assets.

4. First Use Case:

   • Use the generated app.blade.php (Bootstrap) or app.js (Vue/React) as a starting point for your frontend.
   • Example: Extend app.blade.php in your layout:

     @extends('layouts.app')
     

Where to Look First

• Blade Templates: resources/views/auth/ (for auth scaffolding) and resources/views/layouts/.
• JavaScript: resources/js/app.js (Vue/React entry point).
• CSS: resources/sass/app.scss (Bootstrap SASS variables and imports).
• Vite Config: vite.config.js (asset compilation settings).

Implementation Patterns

Usage Patterns

1. Authentication Scaffolding:

   • Generate auth views with:

     php artisan ui bootstrap --auth
     

   • Includes login, registration, password reset, and email verification routes/controllers.

2. Frontend Framework Integration:

   • Vue: Register components in app.js:

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

   • React: Use createRoot (React 18) in app.js:

     import { createRoot } from 'react-dom/client';
     import App from './App';
     createRoot(document.getElementById('app')).render(<App />);
     

3. Customizing Auth Views:

   • Override default views in resources/views/auth/ (e.g., login.blade.php).
   • Extend controllers in app/Http/Controllers/Auth/ (e.g., LoginController.php).

4. Asset Workflow:

   • Development: Run npm run dev to compile assets on-demand.
   • Production: Run npm run build for optimized assets.
   • Use @vite() Blade directive for asset injection:

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

Workflows

1. Bootstrap + Vue/React Hybrid:

   • Use Bootstrap for styling and Vue/React for interactivity.
   • Example: Replace Bootstrap JS components (e.g., modals) with Vue/React equivalents.

2. Modular Frontend:

   • Split app.js into smaller modules (e.g., auth.js, dashboard.js).
   • Dynamically import components:

     const { default: Dashboard } = await import('./components/Dashboard.vue');
     

3. Shared Layouts:

   • Extend resources/views/layouts/app.blade.php for consistent headers/footers.
   • Use Blade components (e.g., @include('partials.navbar')).

Integration Tips

• Laravel Mix Migration:
  • Replace mix-manifest.json references with Vite’s dynamic imports:

    <script type="module" src="@vite('resources/js/app.js')"></script>
    

• Tailwind CSS:
  • Replace Bootstrap with Tailwind by updating app.scss and package.json:

    npm install -D tailwindcss postcss autoprefixer
    

• API Authentication:
  • Use Laravel Sanctum/Passport with Vue/React via Axios:

    axios.post('/login', { email, password });
    

Gotchas and Tips

Pitfalls

1. Asset Compilation Issues:

   • Symlink Missing: Ensure public/build is symlinked or configured in vite.config.js:

     build: {
       outDir: 'public/build',
     }
     

   • Vite Hot Module Replacement (HMR): May not work with Laravel’s default Blade setup. Use @viteReactRefresh for React.

2. Auth Controller Conflicts:

   • Overriding LoginController may break auth scaffolding. Use php artisan ui:auth to regenerate views/controllers.

3. Vue/React Version Mismatches:

   • Ensure package.json versions match Laravel UI’s defaults (e.g., Vue 3, React 18).
   • Example conflict: @vitejs/plugin-vue@4.x with Laravel 12+ (use @vitejs/plugin-vue@3.x if needed).

4. CSRF Token in API Requests:

   • Vue/React apps need CSRF tokens for stateful requests. Use:

     axios.defaults.headers.common['X-CSRF-TOKEN'] = document.querySelector('meta[name="csrf-token"]').content;
     

Debugging

1. Vite Errors:

   • Clear cache:

     npm run dev -- --clear
     

   • Check vite.config.js for misconfigured plugins (e.g., @vitejs/plugin-react).

2. Blade Template Issues:

   • Ensure @vite() directives are placed after opening <body> tags.
   • Debug with {{ dump($errors) }} in Blade templates.

3. Auth Redirect Loops:

   • Verify auth:verify middleware is not misconfigured in app/Http/Kernel.php.
   • Check session() driver in .env (e.g., SESSION_DRIVER=file).

Config Quirks

1. Vite Dev Server:
   • Disable HMR for production:

     // vite.config.js
     server: {
       hmr: process.env.NODE_ENV === 'development',
     }
     

2. Bootstrap Variables:
   • Override defaults in resources/sass/app.scss:

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

3. Laravel Mix Legacy:
   • If migrating from Mix, update webpack.mix.js to Vite by removing it and using vite.config.js.

Extension Points

1. Custom Presets:

   • Extend UiCommand in a service provider:

     UiCommand::macro('tailwind', function () {
         // Scaffold Tailwind setup
     });
     

   • Call with:

     php artisan ui tailwind
     

2. Dynamic Component Loading:

   • Use Laravel’s service container to bind Vue/React components:

     $app->singleton('vue-components', function () {
         return collect([
             'example' => ExampleComponent::class,
         ]);
     });
     

3. API Resource Transformers:

   • Override auth responses in app/Http/Controllers/Auth/RegisteredUserController.php:

     protected function registered(Request $request, $user) {
         return response()->json(['data' => $user]);
     }
     

Pro Tips

• Dark Mode: Use Bootstrap’s dark mode with data-bs-theme="dark" or CSS variables.
• Lazy Loading: Dynamically import routes in Vue/React:

  const Home = () => import('./components/Home.vue');
  

• Testing: Use Laravel’s actingAs() with Vue/React tests:

  test('login', async () => {
      await actingAs(User::factory()->create());
      // Test Vue/React behavior
  });