Download the PHP package dxgx/blade-tailwind-extract without Composer

Blade Tailwind Extract - Tailwind Class Extractor for Laravel

A Laravel package that dramatically reduces Livewire component wire transfer sizes by extracting long Tailwind CSS class strings into short, reusable CSS class names. Perfect for applications with large lists of Livewire components.

The Problem

When using Livewire with Tailwind CSS, long class strings in Blade templates get transferred over the wire on every component update:

With 100 items in a list, this verbose markup significantly impacts performance.

The Solution

Blade Tailwind Extract extracts your Tailwind classes into a CSS file using @apply, replacing them with short class names:

Development Mode (Injected):

Production Mode (Extracted):

Generated CSS:

The a40f hash is derived from the file path, ensuring no conflicts between files.

Features

• ✅ Reduces Livewire wire payload - Short class names instead of verbose Tailwind strings
• ✅ Automated class identification - Wrap command finds and marks repeated class lists
• ✅ Intelligent deduplication - Identical class lists share the same wrapper name
• ✅ Comprehensive pattern support - Works with class="", wire:class="", :class (static & ternary), x-bind:class, @class([]) (simple & conditional)
• ✅ Bidirectional - Extract for production, restore for development
• ✅ Safe - Reserved classes like group, group/, and peer are automatically skipped with informative warnings
• ✅ Collision-free - File-based hashing prevents class name conflicts
• ✅ Pattern matching - Process specific files or entire directories
• ✅ Configurable - Customize prefix, hash length, output path, and more

Installation

Install via Composer as a dev dependency (this is a development tool, not needed in production):

Publish the configuration file (optional):

Usage

Quick Start: 3-Step Workflow

1. Wrap - Automatically identify and mark class lists with semantic names
2. Extract - Convert marked classes into compact CSS
3. Restore - Bring back inline classes for editing

Wrap Classes (Preparation Step)

Before extraction, use the wrap command to automatically identify and mark repeated Tailwind class lists with semantic wrapper names. This helps you see which classes will be extracted and ensures consistent naming for identical class lists.

What it does:

• Scans for class lists with 3+ classes (configurable via --min)
• Automatically deduplicates: identical class lists get the same wrapper name
• Generates semantic names: __adjective-noun-number__ (e.g., __happy-cat-1__)
• Skips patterns that should never be extracted: __, material-symbols-outlined, TW-
• Shows summary of changes with occurrence counts

Before wrapping:

After wrapping:

Notice how identical class lists share the same wrapper name (happy-cat-1), while different lists get unique names.

Supported Class Attribute Patterns

The wrap command supports all major Blade/Livewire/Alpine.js class attribute patterns:

1. Static class Attribute

Standard HTML class attribute:

2. Livewire wire:class Attribute

Livewire's reactive class binding:

3. Alpine.js :class with Static Classes

Dynamic class binding with static string:

4. Alpine.js :class with Ternary Expression

Conditional class switching with ternary operator:

5. Alpine.js x-bind:class Attribute

Explicit Alpine binding syntax:

6. Blade @class Directive (Simple Array)

Blade's class directive with simple string:

7. Blade @class Directive (Conditional Array)

Blade's class directive with conditional classes:

8. Combined Static and Dynamic Classes

Elements with both static class and dynamic :class attributes (wrapped independently):

Note: In this example, the ternary branches have only 2 classes each (below the default minimum of 3), so they aren't wrapped. The static class attribute with 4 classes is wrapped.

Pattern Behavior Summary

• All patterns respect the minimum class count (default: 3, configurable via --min)
• Identical class lists across any pattern type share the same wrapper name
• Already wrapped class lists are skipped (won't double-wrap)
• Protected patterns (containing __, material-symbols-outlined, or starting with TW-) are never wrapped
• Ternary expressions have both branches examined and wrapped independently if they meet the threshold
• Conditional arrays in @class have all string values examined and wrapped independently
• Static and dynamic attributes on the same element are processed independently

Extract Classes (Development → Production)

The target parameter accepts multiple formats:

0. No target (processes all files in search_path with confirmation):

1. Directory (processes all .blade.php files recursively):

2. Single file path:

3. Pattern matching (searches in configured search_path):

4. Multiple targets (comma-separated, can mix patterns and files):

Restore Classes (Production → Development)

Restore Tailwind classes for editing (accepts same target formats as extract):

Automatic CSS Cleanup: When you restore classes, the command automatically removes the restored CSS rules from the output file, keeping your CSS clean and preventing stale rules from accumulating.

Workflow

Option A: Automated (New Files)

1. Wrap your Blade file to identify and mark repeated class lists
2. Extract marked classes to generate compact CSS
3. Commit both Blade files and CSS file

Option B: Manual (Existing Workflow)

1. Manually add __name__ classes __ markers around classes you want to extract
2. Extract to generate compact CSS
3. Commit both Blade files and CSS file

Option C: Editing Existing Extracted Files

1. Restore before editing (restore Tailwind classes to inline format)
2. Edit your Blade files normally
3. Extract after editing (compact back to short class names)
4. Commit both Blade files and CSS file

You can add markers manually or use the wrap command to add them automatically.

Manual approach: Wrap classes you want to extract with double underscores:

Automated approach: Use the wrap command to automatically identify and mark class lists:

After extraction:

Important: The group and peer Tailwind classes cannot be extracted (they break parent-child selectors). The tool will warn and skip them automatically.

Configuration

Configuration file: config/dg-blade-tailwind-extract.php

Note: When the extract command encounters patterns containing reserved classes (like group, group/item, or peer), it will:

• Skip extraction for that pattern
• Display an informative warning showing which patterns were skipped and why
• Continue processing other patterns in the same file

Advanced Usage

Custom CSS Output Path

Working with Livewire Components

The tool works seamlessly with Livewire's ->class([...]) method and Blade's @class([...]) directive:

Before Extraction:

After Extraction:

Wrap Mode (Optional Preparation):**

• Scans for class lists with minimum number of classes (default: 3)
• Automatically deduplicates identical class lists
• Generates semantic wrapper names: __adjective-noun-number__
• Marks class lists: __name__ classes __
• Skips protected patterns (material-symbols-outlined, TW-, etc.)
• Shows summary with occurrence counts

2. Extract Mode:

   • Scans for __name__ tailwind classes __ patterns
   • Generates short class names: {PREFIX}-{HASH}-{NAME}
   • Writes @apply rules to the CSS file
   • Replaces inline classes with short names

3. Restore Mode:

   • Reads existing @apply rules from CSS file
   • Finds short class names in Blade files
   • Restores original Tailwind class strings

4. Extract Mode:

   • Scans for __name__ tailwind classes __ patterns
   • Generates short class names: {PREFIX}-{HASH}-{NAME}
   • Writes @apply rules to the CSS file
   • Replaces inline classes with short names

5. Restore Mode:

   • Reads existing @apply rules from CSS file
   • Finds short class names in Blade files
   • Restores original Tailwind class strings
6. File Hash:
   • Each file gets a unique 4-character hash (configurable)
   • Prevents class name collisions between files
   • Allows same semantic name (card-wrapper) across different files

Gotchas & Best Practices

• ⚠️ Never manually edit TW-* class names in extracted files
• ⚠️ Always restore → edit → extract workflow
• ⚠️ Don't extract group, peer, or other parent-modifier classes
• ✅ Commit both Blade and CSS files together
• ✅ Run extract before deploying to production
• ✅ Run restore before starting development

Testing

Security

If you discover any security-related issues, please email [email protected] instead of using the issue tracker.

Credits

• dxgx

License

The MIT License (MIT). Please see License File for more information.

Changelog

Please see CHANGELOG.md for recent changes.

Contributing

Please see CONTRIBUTING.md for details.