Laravel Cube Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require nasirkhan/laravel-cube
   

2. Configure default framework in .env:

   CUBE_FRAMEWORK=tailwind  # or 'bootstrap'
   

3. For Tailwind users: Add to your CSS file:

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

4. First use case: Replace a basic button with Cube's component:

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

Key First Steps

• Publish views for customization (optional):

  php artisan vendor:publish --tag=cube-views
  

• Explore the icon reference for visual cues.

Implementation Patterns

Framework Agnostic Workflow

1. Global Framework Selection: Set CUBE_FRAMEWORK in .env to default all components to Tailwind or Bootstrap.
2. Per-Component Override:

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

3. Component Composition: Combine components for complex UIs:

   <x-cube::group name="email" label="Email">
       <x-cube::input type="email" name="email" />
       <x-cube::error :messages="$errors->email" />
   </x-cube::group>
   

Livewire Integration

• Cube components work seamlessly with Livewire:

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

• Use loading prop for async states:

  <x-cube::button :loading="true">Processing...</x-cube::button>
  

Form Handling Patterns

1. Validation Integration:

   <x-cube::error :messages="$errors->get('field_name')" />
   

2. Old Input Handling:

   <x-cube::input name="email" :value="old('email')" />
   

3. Required Fields:

   <x-cube::group name="email" label="Email" required>
       <x-cube::input type="email" name="email" required />
   </x-cube::group>
   

Navigation Patterns

• Active State Handling:

  <x-cube::nav-link href="{{ route('dashboard') }}" :active="request()->routeIs('dashboard')">
      Dashboard
  </x-cube::nav-link>
  

• Responsive Links:

  <x-cube::responsive-nav-link href="{{ route('profile') }}">
      Profile
  </x-cube::responsive-nav-link>
  

Dark Mode Support

• Tailwind components automatically support dark mode via:

  <x-cube::button variant="primary" class="dark:bg-gray-800">
      Dark Button
  </x-cube::button>
  

Gotchas and Tips

Common Pitfalls

1. Tailwind CSS Setup:

   • Forgetting to import tailwind.css from the package will break Tailwind-specific components.
   • Fix: Add @import "../../vendor/nasirkhan/laravel-cube/resources/css/tailwind.css"; to your CSS file.

2. Icon Naming:

   • Icons use kebab-case (e.g., adjustments-horizontal), not camelCase or snake_case.
   • Tip: Use the icon reference for valid names.

3. Framework Mismatch:

   • Mixing Tailwind and Bootstrap components may cause styling inconsistencies.
   • Solution: Use per-component overrides sparingly or stick to one framework globally.

4. Published Views Overwrite:

   • Customizing published views requires republishing after updates.
   • Tip: Use php artisan vendor:publish --tag=cube-views --force to overwrite existing files.

Debugging Tips

1. Component Not Rendering:

   • Check for typos in component names (e.g., <x-cube::buton> vs <x-cube::button>).
   • Verify the namespace is correct (e.g., x-cube:: not x-cube.button).

2. Styling Issues:

   • Use framework="tailwind" or framework="bootstrap" to debug per-component rendering.
   • Inspect the generated HTML to identify missing classes or incorrect attributes.

3. Livewire Conflicts:

   • Ensure Livewire 3/4 is installed (composer require livewire/livewire).
   • Tip: Use wire:model alongside Cube form components for two-way binding:

     <x-cube::input wire:model="email" name="email" />
     

Extension Points

1. Customizing Components:

   • Publish and modify views in resources/views/vendor/cube/components/.
   • Example: Override the button component by copying vendor/nasirkhan/laravel-cube/resources/views/components/button.blade.php to your published views directory.

2. Adding New Components:

   • Extend the package by creating custom Blade components in app/View/Components.
   • Tip: Follow Cube’s naming convention (e.g., app/View/Components/Cube/NewComponent.php).

3. Configuration Overrides:

   • Publish the config file:

     php artisan vendor:publish --tag=cube-config
     

   • Modify config/cube.php to change default settings (e.g., icon variants, button variants).

Performance Tips

1. Lazy-Loading Icons:

   • Use class="hidden" and add via JavaScript if icons are not critical for initial render.
   • Example:

     <x-cube::icon name="adjustments-horizontal" class="hidden icon-to-load" />
     <script>
         document.querySelector('.icon-to-load').classList.remove('hidden');
     </script>
     

2. Component Caching:

   • Cube components are Blade views; leverage Laravel’s view caching for production:

     php artisan view:cache
     

3. Tailwind Optimization:

   • Run npx tailwindcss -i input.css -o output.css --watch to purge unused CSS classes from Cube’s Tailwind components.

Advanced Usage

1. Dynamic Framework Selection:

   • Use a helper function to switch frameworks based on user preferences:

     // app/Helpers/CubeHelper.php
     function cubeFramework(): string {
         return session('cube_framework') ?? config('cube.framework');
     }
     

     <x-cube::button framework="{{ cubeFramework() }}">Dynamic Button</x-cube::button>
     

2. Component Slots:

   • Some components support slots (e.g., modals, cards):

     <x-cube::modal>
         <x-slot name="title">Custom Title</x-slot>
         Modal content here.
     </x-cube::modal>
     

3. Integration with Laravel Sharekit:

   • Use Cube for UI and Sharekit for social sharing on specific pages:

     @if($showShareButtons)
         <x-sharekit::buttons :url="route('post.show', $post)" />
     @endif