Blade Tailwind Extract Laravel Package

Getting Started

Minimal Steps

1. Install the package (dev dependency):

   composer require dxgx/blade-tailwind-extract --dev
   

2. Publish config (optional):

   php artisan vendor:publish --tag=blade-tailwind-extract-config
   

3. First use case: Wrap a Blade file

   php artisan dg:blade-tailwind:wrap resources/views/components/card.blade.php
   

   This automatically identifies repeated Tailwind class lists and wraps them with semantic names like __card-wrapper__.

4. Extract to production format:

   php artisan dg:blade-tailwind:extract resources/views/components/card.blade.php
   

   This converts wrapped classes to compact TW-* classes and generates CSS @apply rules.

Implementation Patterns

Core Workflow

1. Wrap → Extract → Commit (New files)

   php artisan dg:blade-tailwind:wrap resources/views/livewire
   php artisan dg:blade-tailwind:extract resources/views/livewire
   

2. Restore → Edit → Extract (Existing files)

   php artisan dg:blade-tailwind:restore resources/views/components
   # Edit Blade files
   php artisan dg:blade-tailwind:extract resources/views/components
   

Pattern-Specific Integration

• Livewire Components: Extract all resources/views/livewire to minimize wire payload.
• Shared Components: Use --min=2 for small components (e.g., buttons).
• Conditional Classes: Wrap both branches of :class ternaries independently.

CI/CD Integration

# Example GitHub Actions workflow
- name: Extract Tailwind classes
  run: |
    php artisan dg:blade-tailwind:wrap resources/views --yy
    php artisan dg:blade-tailwind:extract resources/views --yy

Configuration Tips

• Set hash_length: 5 for larger projects to reduce collision risk.
• Customize reserved_classes to include project-specific patterns.

Gotchas and Tips

Pitfalls

1. Reserved Classes: Attempting to extract group, peer, or group/ classes will fail with warnings. Use --skip-prefix=TW to avoid accidental extraction of existing TW-* classes.

2. File Renaming: Moving Blade files after extraction breaks the file-based hash. Solution: Restore → move → extract.

3. PHP Syntax Errors: The package runs php -l before extraction. Fix syntax errors first.

4. Ternary Expressions: Both branches of :class ternaries are wrapped independently. Ensure each branch meets the --min threshold.

5. CSS Sync: Always commit both Blade files and the generated CSS file together.

Debugging

• Use --dry-run to preview changes without modifying files.
• Check storage/logs/laravel.log for skipped patterns and warnings.
• Run php artisan dg:blade-tailwind:wrap --min=1 to see all potential candidates.

Extension Points

1. Custom Wrapper Names: Override generateWrapperName() in a service provider.
2. Additional Patterns: Extend TailwindExtractorService to support custom attributes.
3. Post-Extraction Hooks: Use Laravel events to trigger actions after extraction.

Pro Tips

• Bulk Operations: Use --yy to skip confirmations in CI/CD.
• Pattern Matching: Use *livewire* to target only Livewire components.
• Conditional Arrays: All strings in @class([...]) are processed independently.

# Example: Extract only Livewire components with 4+ classes
php artisan dg:blade-tailwind:wrap resources/views/livewire --min=4 --yy
php artisan dg:blade-tailwind:extract resources/views/livewire --yy