@culur/prettier-plugin-tailwindcss-group weekly downloads statistics

@culur/prettier-plugin-tailwindcss-group

Prettier plugin to automatically group, format, and simplify Tailwind CSS class names across JSX attributes, object properties, and CVA variant definitions.

✨ Features

This plugin enforces a clean and consistent structure for Tailwind CSS classes. It provides:

• Automatic Grouping: Automatically breaks down long class strings into logically grouped arguments by utility category (Layout, Typography, Visuals, etc.). • Multi-Target Support: Formats JSX attributes (className, wrapperClassName), object properties (className, wrapperclassName), and cva() parameters from class-variance-authority (commonly used in shadcn/ui). • Redundancy Simplification: Flattens unnecessary wrapper functions into pure strings if they are under the threshold. • Comment Preservation: Safely detects and preserves code comments (// and /* ... */) by bailing out on commented nodes to avoid Prettier "Comment was not printed" errors. • Idempotency & Compatibility: Strictly manipulates the Prettier AST. The output is fully compliant with standard Prettier formatting and integrates flawlessly with prettier-plugin-tailwindcss.

💿 Installation

Add @culur/prettier-plugin-tailwindcss-group and prettier-plugin-tailwindcss to your project. prettier-plugin-tailwindcss is a required peer dependency used to resolve official Tailwind CSS compiler sorting and variant hierarchies.

[!NOTE] No need to install tailwind-merge: The required tailwind-merge engine is already bundled directly inside @culur/prettier-plugin-tailwindcss-group. You do not need to install tailwind-merge as a separate dependency unless your application code directly imports utility functions like twMerge() or cn().

_Note: You also need prettier (>=3.0.0) installed in your project._

📖 Usage & Integration

Add to your .prettierrc configuration:

Both plugins share the tailwindFunctions configuration option, so helper functions like cn() or clsx() are sorted and grouped seamlessly.

⚙️ Options

| Option | Type | Default | Description |

| classNameThreshold | int | 10 | Threshold of class names (split by whitespace) to trigger wrapping. | | modifierThreshold | int | 2 | Threshold of modifier/variant classes within a category before splitting into separate lines. | | tailwindFunctions | string[] | ["cn"] | List of helper function names. The first element is used as default wrapper function. Note: tailwindFunctions is also an official option of prettier-plugin-tailwindcss. |

📐 Formatting Rules & Concepts

This plugin inspects AST nodes to find valid styling targets and applies formatting rules.

🔠 Representation Modes

Depending on the target context and rule thresholds, class strings are represented in one of the following AST forms:

• StringLiteral: A raw static string literal "class-1 class-2". • ExpressionStringLiteral: A JSX expression container wrapping a single string literal {"class-1 class-2"} (JSX Attributes only). • ExpressionCall: A helper function call such as {cn('class-1 class-2')} (JSX Attributes) or cn('class-1 class-2') (Object Properties / CVA Parameters). • ExpressionArrayString: An array literal containing string items ['class-1', 'class-2'] (used in CVA parameters).

🎯 Supported Targets

The plugin automatically identifies and formats the following targets in your codebase:

• JSX Attributes: Attributes named className or ending with a case-sensitive suffix ClassName (e.g. wrapperClassName, containerClassName, headerClassName). • Attribute Pattern Matching: Matched using strict suffix matching (ends with 'ClassName'). Exact names like className, wrapperClassName, and containerClassName match, whereas uppercase variants like CLASSNAME or unrelated attributes like class / id are ignored. • Bypassed Cases: Attributes with no value (e.g. ) or empty strings (className="") are safely bypassed without transformation. • Generated Modes: StringLiteral or ExpressionCall based on the class count threshold. • Object Properties: Static properties named className or ending with ClassName / className (case-sensitive, e.g., wrapperClassName, innerclassName). • Generated Modes: ExpressionCall only.

Note: Formatted only when calling a helper function in tailwindFunctions (e.g. cn(...)) to avoid false positives on non-CSS properties. The ExpressionCall wrapper is intentionally preserved (never simplified to StringLiteral) so you can freely add classes later without manual re-wrapping, and sorting plugins continue to work seamlessly. Computed keys are not supported.

• CVA Function Calls: Arguments inside cva(...) functions from class-variance-authority (commonly used in libraries like shadcn/ui): • Base classes: params[0] • Variant classes: params[1]['variants'][][] • Compound variant classes: params[1]['compoundVariants'][]['class'] or ['className'] • Ignored / Non-Class Keys: Configuration objects like defaultVariants (which define variant option identifiers) and condition selector keys inside compoundVariants (such as intent: 'primary', size: 'small') are non-class properties and are strictly left untouched. • Spread Elements: When cva is called with a spread config (e.g. cva(base, ...spreadConfig)), the plugin formats params[0] (base classes) and safely skips ...spreadConfig since dynamic objects cannot be statically grouped at format time. • Generated Modes: StringLiteral, ExpressionArrayString, or ExpressionCall based on the input node type and class count threshold.

Note: Matches direct cva(...) function calls. Aliased imports (e.g. import { cva as createVariants }) are intentionally not tracked to maintain high performance and simplicity without requiring complex AST scope analysis.

⚡ Core Rules

1. Short String Simplification (≤ classNameThreshold)

Targets with class count ≤ classNameThreshold are simplified back to StringLiteral format. Redundant expressions like {"..."}, ['...'], or cn('...') containing a single static string under the threshold are simplified to plain strings.

Before:…

Description from the npm listing.