Lux Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require forlaravel/lux
   

   Publish the package assets (Blade components, Tailwind config, and any default views):

   php artisan vendor:publish --provider="ForLaravel\Lux\LuxServiceProvider" --tag="lux-assets"
   

2. Tailwind Integration Ensure your tailwind.config.js includes Lux’s default theme (or extend it):

   module.exports = {
     theme: {
       extend: {
         colors: {
           primary: {
             DEFAULT: '#3b82f6',
             // ... other Lux defaults
           },
         },
       },
     },
   }
   

3. First Use Case Render a Lux button in a Blade view:

   @luxButton('Click Me', 'primary')
   

   Or use the full component syntax:

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

Implementation Patterns

Component-Based Workflow

• Reusable Components: Lux provides pre-built components (e.g., button, card, modal, alert). Use them like native Blade components:

  <x-lux.card>
      <x-slot name="header">
          <h3>Title</h3>
      </x-slot>
      Content here.
  </x-lux.card>
  

• Slot-Based Customization: Leverage slots for dynamic content:

  <x-lux.modal>
      <x-slot name="title">Confirm Action</x-slot>
      Are you sure?
  </x-lux.modal>
  

Theming and Styling

• Tailwind Variants: Customize via Tailwind classes (Lux components are class-based):

  @luxButton('Save', 'success', ['class' => 'rounded-lg'])
  

• Global Overrides: Extend Lux’s default theme in tailwind.config.js:

  module.exports = {
    theme: {
      extend: {
        colors: {
          danger: '#ef4444', // Override Lux's default
        },
      },
    },
  }
  

Integration with Laravel Features

• Form Integration: Pair with Laravel Collective or native forms:

  <x-lux.form>
      <x-lux.input label="Email" name="email" type="email" />
      <x-lux.button type="submit">Submit</x-lux.button>
  </x-lux.form>
  

• Validation Feedback: Use Lux alerts with Laravel validation errors:

  @if($errors->any())
      <x-lux.alert type="error">
          {{ $errors->first() }}
      </x-lux.alert>
  @endif
  

Dynamic Data Binding

• Dynamic Props: Pass dynamic data via Blade variables:

  @luxButton($dynamicText, $dynamicVariant)
  

• Component Props: Use with() for complex data:

  <x-lux.card :user="$user" />
  

  (Ensure the component accepts $user in its props.)

Gotchas and Tips

Pitfalls

1. Tailwind Conflicts

   • Lux assumes Tailwind is configured. If using custom Tailwind paths, ensure Lux’s assets are compiled last in your build process.
   • Fix: Add Lux’s CSS file after your main Tailwind file in resources/css/app.css.

2. Component Registration

   • Lux components must be auto-discovered. If missing, manually register them in AppServiceProvider:

     public function boot(): void {
         Blade::component('lux.button', \ForLaravel\Lux\Components\Button::class);
     }
     

3. Slot Naming

   • Lux components use slot for default content and named slots (e.g., header, footer). Misnaming slots will break rendering.
   • Tip: Check the component’s Blade template for correct slot names.

4. Dependency on shadcn/ui

   • Lux is a wrapper for shadcn/ui components. If shadcn/ui updates break Lux, check the Lux changelog or open an issue.

Debugging

• Inspect Rendered HTML: Use browser dev tools to verify Lux components render as expected. Look for missing classes or slots.
• Log Component Props: Add {{ dd($props) }} inside a component’s Blade template to debug passed data.

Extension Points

1. Custom Components

   • Extend Lux by creating new components in app/View/Components/Lux. Example:

     namespace App\View\Components\Lux;
     use ForLaravel\Lux\Components\BaseComponent;
     class CustomButton extends BaseComponent { ... }
     

   • Register the namespace in AppServiceProvider.

2. Override Defaults

   • Copy Lux’s Blade templates to resources/views/vendor/lux/ to customize without modifying the package directly.

3. Add New Variants

   • Extend Tailwind’s theme to support new Lux variants (e.g., dark mode):

     module.exports = {
       darkMode: 'class',
       theme: {
         extend: {
           colors: {
             primary: {
               dark: '#1e40af',
             },
           },
         },
       },
     }
     

Performance Tips

• Lazy-Load Components: Use @once for heavy Lux components to avoid re-rendering:

  @once
      <x-lux.modal>...</x-lux.modal>
  @endonce
  

• Cache Views: Enable Laravel’s view caching for Lux-heavy pages:

  php artisan view:cache