Laravel Bootstrap Component Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require quantavoxel/laravel-bootstrap-component
   

   Run migrations (if applicable) and publish assets/config:

   php artisan vendor:publish --provider="QuantaVoxel\BootstrapComponent\BootstrapComponentServiceProvider" --tag="config"
   php artisan vendor:publish --provider="QuantaVoxel\BootstrapComponent\BootstrapComponentServiceProvider" --tag="assets"
   

2. First Use Case: Render a pre-built component (e.g., navbar) in a Blade view:

   <x-bootstrap::navbar title="My App" brand-link="/">
       <x-slot name="items">
           <x-bootstrap::nav-item href="/">Home</x-bootstrap::nav-item>
           <x-bootstrap::nav-item href="/about">About</x-bootstrap::nav-item>
       </x-slot>
   </x-bootstrap::navbar>
   

3. Where to Look First:

   • Documentation: Check resources/docs/ (if published) or the GitHub README.
   • Component List: Browse vendor/quantavoxel/laravel-bootstrap-component/src/View/Components/ for available components.
   • Config: Review config/bootstrap-component.php for global settings (e.g., default icon set, asset paths).

Implementation Patterns

Core Workflows

1. Component-Based UI Development:

   • Use <x-bootstrap::* /> tags for reusable UI elements (e.g., <x-bootstrap::alert type="success" />).
   • Pass dynamic data via attributes or slots:

     <x-bootstrap::card title="User Profile">
         <x-slot name="content">
             {{ $user->bio }}
         </x-slot>
     </x-bootstrap::card>
     

2. Icon System Integration:

   • Register an icon set in config/bootstrap-component.php:

     'icons' => [
         'default' => 'lucide', // or 'fontawesome', 'solar', etc.
     ],
     

   • Use icons in components:

     <x-bootstrap::button icon="home" />
     

   • Dynamically switch icon sets per view:

     <x-bootstrap::icon name="home" set="solar" />
     

3. Asset Management:

   • Pre-bundled Bootstrap 5 assets (CSS/JS) are auto-loaded. No manual @vite or @mix directives needed.
   • Customize global styles by publishing the assets tag and modifying public/vendor/bootstrap-component/css/app.css.

4. Extending Components:

   • Override default components by publishing them:

     php artisan vendor:publish --tag="bootstrap-components"
     

   • Modify published files in resources/views/vendor/bootstrap-component/.

Integration Tips

• Laravel Mix/Vite: Disable Bootstrap asset bundling in your build tool if using the package’s pre-bundled assets.
• Tailwind CSS: Works seamlessly alongside Tailwind. Use Bootstrap components for high-level structure and Tailwind for custom styling.
• Dark Mode: Enable via config:

  'dark_mode' => env('BOOTSTRAP_DARK_MODE', false),
  

• Localization: Components support Blade @lang directives for multi-language projects.

Gotchas and Tips

Common Pitfalls

1. Asset Conflicts:

   • Issue: Double-loading Bootstrap JS/CSS if your project already bundles Bootstrap.
   • Fix: Disable the package’s assets in config/bootstrap-component.php:

     'assets' => [
         'css' => false,
         'js'  => false,
     ],
     

     Then manually include your preferred version.

2. Icon Set Mismatches:

   • Issue: Using an icon not registered in the config or missing from the chosen icon set.
   • Fix: Verify the icon set name in config/bootstrap-component.php and ensure the icon exists in the set (e.g., lucide vs. fontawesome).

3. Component Overrides:

   • Issue: Changes to published components are lost after updates.
   • Fix: Use php artisan vendor:publish --tag="bootstrap-components" after updating the package to merge changes.

4. Blade Component Namespace:

   • Issue: x-bootstrap::* not resolving.
   • Fix: Ensure the service provider is registered in config/app.php and the package is installed correctly.

Debugging Tips

• Check Published Assets: Verify files exist in public/vendor/bootstrap-component/ after publishing.
• Clear Views Cache: Run php artisan view:clear if components fail to render.
• Inspect Config: Use php artisan config:clear to reset config if changes aren’t applying.
• Icon Debugging: Temporarily enable debug mode in config:

  'icons' => [
      'debug' => true, // Logs missing icons to Laravel logs
  ],
  

Extension Points

1. Custom Icon Sets:

   • Add new icon sets by extending the IconServiceProvider or publishing the config to add a custom provider.

2. Global Component Modifiers:

   • Use the global_modifiers config array to apply classes to all components:

     'global_modifiers' => [
         'navbar' => 'bg-dark',
     ],
     

3. Dynamic Asset Loading:

   • Conditionally load assets based on routes or user roles:

     @if(auth()->check())
         @bootstrapComponentScript('custom-js')
     @endif
     

4. Testing:

   • Test components in isolation using Laravel’s render() helper:

     $html = \Illuminate\Support\Facades\Blade::render('<x-bootstrap::navbar />');