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 to either tailwind or bootstrap.

3. Tailwind Setup (if using Tailwind CSS v4): Add to your main CSS file:

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

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

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

Where to Look First

• Documentation: Start with the README for installation and basic usage.
• Icon Reference: Check docs/icons.md for available icons and their usage.
• Published Views: After publishing views (php artisan vendor:publish --tag=cube-views), inspect resources/views/vendor/cube/components/ for customization.

Implementation Patterns

Usage Patterns

1. Framework Agnostic Components: Use the same Blade component syntax regardless of the underlying CSS framework:

   <!-- Uses Tailwind by default -->
   <x-cube::button variant="primary">Default</x-cube::button>
   
   <!-- Override per component -->
   <x-cube::button framework="bootstrap" variant="primary">Bootstrap</x-cube::button>
   

2. Form Handling: Group form inputs with labels, errors, and validation:

   <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. Navigation: Use responsive navigation components with active state support:

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

4. Icons: Embed icons with customizable variants and classes:

   <x-cube::icon name="bell" variant="solid" class="text-red-500" />
   

5. Livewire Integration: Cube components work seamlessly with Livewire. Use them in Livewire views like any other Blade component.

Workflows

1. Component-Based Development:

   • Replace repetitive HTML snippets (e.g., buttons, modals) with reusable Blade components.
   • Example: Replace all primary buttons in a project with <x-cube::button variant="primary">.

2. Theming:

   • Publish and override component views to customize styles or behavior.
   • Example: Publish views, then modify resources/views/vendor/cube/components/button.blade.php.

3. Dark Mode:

   • For Tailwind-based components, leverage Cube’s built-in dark mode support by using Tailwind’s dark mode classes in your published views.

4. Progressive Adoption:

   • Start by replacing one type of component (e.g., buttons) and gradually adopt others.
   • Use per-component framework overrides to test Bootstrap vs. Tailwind side-by-side.

Integration Tips

1. Tailwind CSS:

   • Ensure Tailwind’s content configuration includes Cube’s views:

     content: [
         './resources/views/**/*.blade.php',
         './vendor/nasirkhan/laravel-cube/resources/views/**/*.blade.php',
     ],
     

   • Use Cube’s Tailwind-specific classes (e.g., bg-blue-500 for buttons) directly in Blade.

2. Bootstrap 5:

   • Cube’s Bootstrap components use standard Bootstrap classes (e.g., btn-primary).
   • Ensure Bootstrap’s CSS and JS are properly loaded in your layout.

3. Livewire:

   • Cube components work out-of-the-box with Livewire. Example:

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

4. Customization:

   • Extend components by publishing their views and adding custom logic:

     <!-- resources/views/vendor/cube/components/button.blade.php -->
     @props(['customProp' => false])
     <button {{ $attributes }}>
         @if($customProp)
             Custom Button
         @else
             {{ $slot }}
         @endif
     </button>
     

Gotchas and Tips

Pitfalls

1. Tailwind CSS Setup:

   • Issue: Forgetting to import Cube’s Tailwind CSS file (@import "../../vendor/nasirkhan/laravel-cube/resources/css/tailwind.css") can break Tailwind-based components.
   • Fix: Add the import to your main CSS file if using Tailwind v4.

2. Framework Mismatch:

   • Issue: Using a Tailwind-specific class (e.g., bg-blue-500) in a Bootstrap component or vice versa.
   • Fix: Stick to the framework’s native classes or use per-component overrides:

     <x-cube::button framework="tailwind" class="bg-blue-500">Tailwind Button</x-cube::button>
     

3. Icon Availability:

   • Issue: Using an icon name that doesn’t exist in the Flowbite Blade Icons pack.
   • Fix: Check docs/icons.md for the full list of available icons.

4. Published Views Overwrite:

   • Issue: Updating the package may overwrite custom published views.
   • Fix: Keep a backup of modified views or use mergeConfigPath in config/cube.php to preserve customizations.

5. Livewire Conflicts:

   • Issue: Cube components with wire: directives may conflict if not properly scoped.
   • Fix: Ensure Livewire components are correctly namespaced and avoid duplicate IDs.

Debugging

1. Component Not Rendering:

   • Verify the component namespace is correct (e.g., <x-cube::button>).
   • Check for typos in the component name or props.

2. Styles Not Applying:

   • For Tailwind: Ensure the @import is in your CSS and Tailwind is scanning Cube’s views.
   • For Bootstrap: Verify Bootstrap’s CSS is loaded before Cube’s components.

3. Dark Mode Issues:

   • Ensure your Tailwind config includes dark mode:

     darkMode: 'class',
     

   • Add dark: variants to Cube’s published views if needed.

Tips

1. Component Props:

   • Use php artisan vendor:publish --tag=cube-config to inspect available props for each component in config/cube.php.

2. Dark Mode:

   • For Tailwind components, add dark: classes to published views:

     <button class="bg-blue-500 dark:bg-blue-700">
     

3. Performance:

   • Lazy-load non-critical components (e.g., modals) using Alpine.js or Livewire.

4. Testing:

   • Test components in isolation using Laravel’s test helpers:

     $this->blade('<x-cube::button>Test</x-cube::button>')->assertSee('button');
     

5. Custom Icons:

   • Extend the icon pack by publishing the icon views and adding custom SVG files to resources/views/vendor/cube/icons/.

6. Framework-Specific Logic:

   • Use Blade @if to conditionally render framework-specific markup:

     @if($framework === 'tailwind')
         <div class="p-4 bg-gray-100">
     @else
         <div class="p-4 bg-light">
     @endif
     

7. Configuration:

   • Customize default props globally in config/cube.php:

     'defaults' => [
         'framework' => 'tailwind',
         'button' => [
             'size' => 'md',
         ],
     ],
     

8. Companion Packages:

   • Use nasirkhan/laravel-sharekit for social sharing without bloating Cube:

     <x-sharekit::buttons :url="$post->url" />