Larabite Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require destech-hasar-cozumleri-a-s/larabite
   npm install flowbite
   

   Add the package's Tailwind directives to resources/css/app.css:

   @tailwind base;
   @tailwind components;
   @tailwind utilities;
   @import 'larabite/flowbite';
   

2. Publish Assets

   php artisan larabite:install
   npm run dev  # or build for production
   

3. First Component Usage In a Blade template, use a pre-built component like a button:

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

   Verify the component renders with Tailwind styling.

4. Livewire Integration For Livewire components, ensure your Livewire component extends Larabite\Livewire\Component:

   use Larabite\Livewire\Component;
   class MyComponent extends Component { ... }
   

Implementation Patterns

Core Workflows

1. Component Discovery Browse components via:

   • Blade tags (<x-component-name>)
   • Documentation (e.g., /docs/components/buttons)
   • IDE autocomplete (Laravel IDE Helper recommended)

2. Theming & Customization Override default styles by extending Flowbite’s CSS classes:

   /* resources/css/larabite.css */
   .btn-primary {
       @apply bg-blue-700 hover:bg-blue-800;
   }
   

   Recompile assets after changes.

3. Dynamic Props Pass props to components for dynamic behavior:

   <x-dropdown :items="$menuItems" active="dashboard" />
   

   Use public $propName in component classes for Livewire.

4. Dark Mode Toggle via Alpine.js:

   <x-theme-toggle />
   

   Or manually in Blade:

   <div x-data="{ darkMode: false }" x-bind:class="{ 'dark': darkMode }">
       <!-- Content -->
   </div>
   

5. Form Handling Use built-in form components with Livewire validation:

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

   // Livewire component
   public $email;
   protected $rules = ['email' => 'required|email'];
   

6. Modals & Dialogs Initialize modals via Alpine.js:

   <x-modal id="my-modal" :show="true">
       <x-slot name="title">Title</x-slot>
       <p>Modal content</p>
   </x-modal>
   

   Control visibility with x-data or Livewire.

Integration Tips

• Livewire + Alpine.js: Use wire:ignore for Alpine components inside Livewire:

  <div wire:ignore>
      <x-alpine-component />
  </div>
  

• Partial Updates: Leverage Livewire’s update() for real-time UI changes without full page reloads.
• Asset Optimization: Use Laravel Mix/Vite to purge unused CSS/JS for production builds.
• Testing: Test components in isolation using Laravel’s Blade testing helpers:

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

Gotchas and Tips

Pitfalls

1. Asset Conflicts

   • Issue: Tailwind/Javascript conflicts if multiple UI packages are installed.
   • Fix: Audit resources/js/app.js and resources/css/app.css for duplicate imports. Use @import sparingly.

2. Livewire Component Naming

   • Issue: Naming Livewire components the same as Blade components causes conflicts.
   • Fix: Prefix Livewire components (e.g., LarabiteButton instead of Button).

3. Dark Mode State Persistence

   • Issue: Dark mode toggle resets on page reload.
   • Fix: Store preference in localStorage:

     <x-theme-toggle x-data="{
         darkMode: JSON.parse(localStorage.getItem('dark-mode')) || false,
         toggle() { darkMode = !darkMode; localStorage.setItem('dark-mode', darkMode) }
     }" />
     

4. Alpine.js Event Listeners

   • Issue: Alpine events (e.g., @click) may not trigger in Livewire components.
   • Fix: Use wire:click for Livewire interactions or wire:ignore for Alpine-only components.

5. Component Props Validation

   • Issue: Undefined props in Blade components may throw errors.
   • Fix: Define default props in component classes:

     public $size = 'md'; // Default value
     

Debugging

1. Tailwind Classes

   • Use tailwindcss-intellisense in VSCode for autocomplete.
   • Check compiled CSS (public/build/css/app.css) for missing classes.

2. Livewire Component Lifecycle

   • Override mount() and hydrate() for debugging:

     public function mount() {
         Log::info('Component mounted');
     }
     

3. Alpine.js State

   • Inspect x-data state in browser dev tools (Elements > Computed).
   • Use x-init for initialization logic:

     <div x-data="{ count: 0 }" x-init="console.log('Initialized')">
     

4. Asset Compilation

   • Clear caches after changes:

     php artisan view:clear
     npm run dev
     

Extension Points

1. Custom Components

   • Extend existing components by copying from resources/views/vendor/larabite/ and overriding in resources/views/components/.

2. Flowbite Plugins

   • Integrate additional Flowbite plugins (e.g., flowbite-datepicker) by:
     1. Installing via npm.
     2. Importing in resources/js/app.js:

        import flowbite from 'flowbite';
        flowbite();
        

3. Livewire Hooks

   • Use Livewire’s hooks for component lifecycle events:

     public function boot() {
         Livewire::component('larabite-button', \Larabite\Components\Button::class);
     }
     

4. Dark Mode System

   • Override dark mode classes globally in tailwind.config.js:

     darkMode: 'class',
     theme: {
         extend: {
             colors: {
                 dark: {
                     primary: '#1e293b',
                 }
             }
         }
     }
     

5. Accessibility

   • Extend WCAG compliance by adding ARIA attributes:

     <x-button aria-label="Submit form">Submit</x-button>