Shadcn Ui Blade Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require lundholm.dev/shadcn-ui-blade
   

   Publish the Blade components (if needed):

   php artisan vendor:publish --provider="LundholmDev\ShadcnUiBlade\ShadcnUiBladeServiceProvider" --tag="shadcn-ui-blade"
   

   (Note: Check the latest docs for updated publish tags or config options.)

2. First Use Case Use a pre-built component in a Blade view:

   <x-shadcn-button>
       Click Me
   </x-shadcn-button>
   

   (Verify the component name matches the package’s naming convention—e.g., shadcn-button, shadcn-input.)

3. Where to Look First

   • Package Docs: Check the GitHub README.md for component lists, customization guides, and CLI tools (if available).
   • Published Assets: Inspect resources/views/vendor/shadcn-ui-blade/ for default templates.
   • Tailwind Integration: Ensure your tailwind.config.js includes the package’s required classes (e.g., @shadcn/ui prefix).

Implementation Patterns

Usage Patterns

1. Component Composition Nest components for complex UIs:

   <x-shadcn-card>
       <x-slot name="header">
           <h3>Header</h3>
       </x-slot>
       <x-shadcn-button>Action</x-shadcn-button>
   </x-shadcn-card>
   

   (Use x-slot for named slots, like header, footer, or default.)

2. Dynamic Props Pass props via Blade syntax:

   <x-shadcn-button type="submit" disabled="{{ $isLoading }}">
       Submit
   </x-shadcn-button>
   

   (Check the package’s component docs for supported props—e.g., variant, size.)

3. Customization Override defaults by publishing and modifying the component files:

   php artisan vendor:publish --tag="shadcn-ui-blade" --force
   

   Edit files in resources/views/vendor/shadcn-ui-blade/components/.

4. Form Integration Use with Laravel Collective or native Blade forms:

   <x-shadcn-input type="email" name="email" :value="old('email')">
       <x-slot name="label">Email</x-slot>
   </x-shadcn-input>
   

Workflows

• Theming: Extend Tailwind’s theme to match ShadCN’s design system:

  // tailwind.config.js
  module.exports = {
      theme: {
          extend: {
              colors: {
                  primary: {
                      DEFAULT: '#3b82f6',
                      // ... other variants
                  },
              },
          },
      },
  };
  

• Dark Mode: Ensure your tailwind.config.js includes darkMode: 'class' and test components with dark: variants.

Integration Tips

• Livewire/Alpine: Combine with Alpine.js for interactivity:

  <x-shadcn-button x-on:click="alert('Clicked!')">Alpine Button</x-shadcn-button>
  

• Validation: Pair with Laravel validation messages:

  <x-shadcn-input :error="$errors->has('email')">
      <x-slot name="error">{{ $errors->first('email') }}</x-slot>
  </x-shadcn-input>
  

• Testing: Use Pest/Laravel’s testing tools to assert component rendering:

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

Gotchas and Tips

Pitfalls

1. Component Naming

   • Issue: Components may not render if the Blade tag name doesn’t match the package’s convention (e.g., <x-shadcn-button> vs. <x-button>).
   • Fix: Verify the exact tag names in the package’s README or published files.

2. Missing Dependencies

   • Issue: ShadCN UI relies on Tailwind CSS. If Tailwind isn’t installed or configured, components will break.
   • Fix: Install Tailwind via npm and ensure @tailwind directives are in resources/css/app.css.

3. Slot Conflicts

   • Issue: Named slots (e.g., header, footer) may override unexpected content if not handled.
   • Fix: Explicitly define slots in your Blade:

     <x-shadcn-card>
         <x-slot name="header">Custom Header</x-slot>
         <p>Content</p>
     </x-shadcn-card>
     

4. Prop Binding

   • Issue: Dynamic props (e.g., :disabled) may not work if the component uses static attributes.
   • Fix: Check the component’s source for supported dynamic props or use {{ }} syntax for simple bindings.

Debugging

• Inspect Published Files: If a component renders incorrectly, compare it to the original in vendor/lundholm-dev/shadcn-ui-blade/src/.
• Tailwind Conflicts: Use !important sparingly; debug with Tailwind’s JIT mode or npx tailwindcss -i for errors.
• Blade Cache: Clear Blade cache after publishing updates:

  php artisan view:clear
  

Config Quirks

• No Config File: This package likely uses zero-config. Check for environment variables or service provider bindings if customization is needed.
• Asset Paths: If using custom icons/fonts, ensure paths in the component’s Blade files point to the correct public/ or node_modules/ locations.

Extension Points

1. Create Custom Components Extend the package by copying a base component (e.g., shadcn-button) and modifying it in resources/views/vendor/shadcn-ui-blade/components/.

   <!-- resources/views/vendor/shadcn-ui-blade/components/shadcn-my-button.blade.php -->
   <button class="bg-red-500 text-white p-2 rounded">
       {{ $slot }}
   </button>
   

   Use it as <x-shadcn-my-button>.

2. Add New Components Fork the package or submit PRs to add missing components (e.g., shadcn-dialog, shadcn-tooltip).

3. JavaScript Enhancements Augment components with Alpine.js or vanilla JS by extending their classes:

   // resources/js/app.js
   document.addEventListener('alpine:init', () => {
       Alpine.data('shadcnButton', () => ({
           click() { console.log('Custom logic'); }
       }));
   });
   

   Then bind in Blade:

   <x-shadcn-button x-data="shadcnButton()" x-on:click="click">Click</x-shadcn-button>