Laravel Ui Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require schaefersoft/laravel-ui
   

   Publish assets (if needed):

   php artisan vendor:publish --provider="Schaefersoft\LaravelUI\LaravelUIServiceProvider" --tag=public
   

2. Tailwind Configuration: Update tailwind.config.js as per the README, ensuring:

   • @tailwindcss/forms plugin is added.
   • Vendor paths are included in content.
   • Theme colors are extended (or customize via uicolors.app).

3. First Use Case: Include the package’s base styles in your resources/css/app.css:

   @import 'vendor/schaefersoft/laravel-ui/resources/css/laravel-ui';
   

   Use a component (e.g., a button) in a Blade template:

   <x-laravel-ui::button type="primary">Click Me</x-laravel-ui::button>
   

Implementation Patterns

Component Integration

1. Blade Components: The package provides reusable Blade components (e.g., buttons, modals, alerts). Use them via:

   @laravelUI('button', ['type' => 'success'], 'Save')
   

   Or as standalone:

   <x-laravel-ui::button type="danger">Delete</x-laravel-ui::button>
   

2. Dynamic Styling: Leverage Tailwind’s arbitrary values for customization:

   <x-laravel-ui::button :class="{ 'bg-blue-500': $isPrimary }">Submit</x-laravel-ui::button>
   

3. JavaScript Dependencies: For interactive components (e.g., modals), include the package’s JS:

   <script src="{{ asset('vendor/schaefersoft/laravel-ui/resources/js/laravel-ui.js') }}"></script>
   

   Initialize components via data attributes:

   <x-laravel-ui::modal id="example-modal" data-target="#modal-content">
       <!-- Modal content -->
   </x-laravel-ui::modal>
   

4. Form Integration: Use the @tailwindcss/forms plugin for styled inputs:

   <x-laravel-ui::input type="email" name="email" placeholder="Email" />
   

   Pair with validation feedback:

   @error('email')
       <x-laravel-ui::alert type="error">{{ $message }}</x-laravel-ui::alert>
   @enderror
   

5. Layout Templates: Extend the package’s base layout (if published) for consistency:

   @extends('laravel-ui::layouts.app')
   @section('content')
       <!-- Your content -->
   @endsection
   

Gotchas and Tips

Pitfalls

1. Missing Tailwind Setup:

   • Issue: Components render unstyled if tailwind.config.js isn’t updated.
   • Fix: Verify content paths and plugins are correctly configured.

2. Theme Color Overrides:

   • Issue: Custom theme colors may clash with existing Tailwind classes.
   • Fix: Use !important sparingly; prefer Tailwind’s utility classes for overrides:

     .custom-button { @apply bg-theme-500 !important; }
     

3. JavaScript Conflicts:

   • Issue: Interactive components may fail if jQuery or other libraries conflict.
   • Fix: Check the package’s JS dependencies and isolate scripts:

     <script src="{{ asset('vendor/schaefersoft/laravel-ui/resources/js/laravel-ui.js') }}" defer></script>
     

4. Component Naming:

   • Issue: Blade components may not resolve if namespacing is incorrect.
   • Fix: Use the exact namespace (e.g., x-laravel-ui::button).

5. Asset Publishing:

   • Issue: Custom styles/JS may not update after changes.
   • Fix: Republish assets or use Laravel Mix/Vite for local development:

     npm run dev
     

Debugging Tips

• Inspect Elements: Use browser dev tools to verify Tailwind classes are applied.
• Check Console: Look for 404 errors on missing JS/CSS files (common with incorrect paths).
• Tailwind Debugging: Enable safelist in tailwind.config.js for dynamic classes:

  safelist: [
      'bg-theme-500',
      'text-theme-100',
      // Add other dynamic classes
  ],
  

Extension Points

1. Custom Components: Extend existing components by copying Blade files from vendor/ to resources/views/vendor/laravel-ui/ and modify them.

2. Theme Customization: Override the default theme colors by extending the colors object in tailwind.config.js:

   extend: {
       colors: {
           theme: {
               DEFAULT: '#f49d0c', // Override default 500
               // Add custom shades
           }
       }
   }
   

3. Localization: The package lacks built-in localization. Add translations via Laravel’s lang files:

   // resources/lang/en/laravel-ui.php
   return [
       'button' => [
           'save' => 'Save Changes',
       ],
   ];
   

   Use in Blade:

   <x-laravel-ui::button>{{ __('laravel-ui.button.save') }}</x-laravel-ui::button>
   

4. Dark Mode: Enable Tailwind’s dark mode in tailwind.config.js:

   darkMode: 'class',
   

   Use dark: variants in components:

   <x-laravel-ui::button :class="{ 'dark:bg-theme-700': true }">Dark Button</x-laravel-ui::button>