Laravel Cube Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require nasirkhan/laravel-cube
   

   Automatically registers the service provider.

2. Configure Default Framework: Set CUBE_FRAMEWORK in .env:

   CUBE_FRAMEWORK=tailwind  # or 'bootstrap'
   

3. Tailwind CSS Setup (if using Tailwind): Add to resources/css/app.css:

   @import "../../vendor/nasirkhan/laravel-cube/resources/css/tailwind.css";
   

4. First Use Case: Render a button in a Blade view:

   <x-cube::button variant="primary">Click Me</x-cube::button>
   

Implementation Patterns

Core Workflows

1. Framework-Agnostic Development: Use the framework prop to switch between Tailwind/Bootstrap per component:

   <x-cube::button framework="bootstrap" variant="primary">Bootstrap Button</x-cube::button>
   

2. Form Handling: Wrap inputs with <x-cube::group> for consistent validation/error display:

   <x-cube::group name="email" label="Email" required>
       <x-cube::input type="email" name="email" :value="old('email')" required />
       <x-cube::error :messages="$errors->get('email')" />
   </x-cube::group>
   

3. Modal Integration:

   • Tailwind (Alpine.js):

     <x-cube::modal name="confirm">
         <!-- Content -->
     </x-cube::modal>
     <x-cube::button x-on:click="$dispatch('open-modal', 'confirm')">Open</x-cube::button>
     

   • Bootstrap: Use data-bs-* attributes for native Bootstrap modal triggers.

4. Livewire Compatibility: Cube components work seamlessly with Livewire. Example:

   <x-cube::button wire:click="save" :loading="$processing">
       Save
   </x-cube::button>
   

Integration Tips

• Dark Mode: Tailwind components automatically support dark mode via dark: variants.
• Icon System: Use <x-cube::icon> with Flowbite icons (200+ available). Example:

  <x-cube::icon name="adjustments-horizontal" class="text-blue-500" />
  

• Global Overrides: Publish config (php artisan vendor:publish --tag=cube-config) to customize variants (e.g., button colors).

Gotchas and Tips

Pitfalls

1. Tailwind CSS Purge: Forgetting to @import the Cube CSS file in Tailwind v4+ causes missing utility classes (e.g., buttons appear invisible). Fix: Add the import to app.css.

2. Bootstrap JS Dependencies: Bootstrap components (e.g., modals, dropdowns) require Bootstrap JS. Ensure you’ve included it in your layout:

   <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
   

3. Alpine.js Conflicts: Tailwind components use Alpine.js. If you’re not using Livewire, manually include Alpine:

   <script src="//unpkg.com/alpinejs" defer></script>
   

4. Framework Mismatch: Mixing Tailwind/Bootstrap frameworks in the same view may cause styling inconsistencies. Stick to one framework per view or use the framework prop explicitly.

Debugging

• Component Props: Use dd($component) in a Blade view to inspect available props for a component.
• View Publishing: Override views by publishing them (php artisan vendor:publish --tag=cube-views) and modifying resources/views/vendor/cube/components/.

Extension Points

1. Custom Variants: Extend button variants by publishing the config and adding to config/cube.php:

   'tailwind' => [
       'buttons' => [
           'custom' => 'bg-green-600 hover:bg-green-700 text-white',
       ],
   ],
   

2. New Components: Clone existing component views from vendor/nasirkhan/laravel-cube/resources/views/components/ and publish them.

3. Type Safety: Cube uses Blade’s type system. For custom props, extend the component class in app/Providers/AppServiceProvider.php:

   use NasirKhan\Cube\Components\Button;
   
   Button::macro('customMethod', function () { ... });
   

Performance Tips

• Lazy-Load Icons: Dynamically load icons only when needed by using conditional rendering or Alpine.js.
• Bootstrap CSS: Only include Bootstrap CSS if using Bootstrap components to reduce bundle size.