eslint-plugin-readable-tailwind

readable-tailwind

ESLint plugin to automatically break up long tailwind class strings into multiple lines based on a specified print width or class count. This improves readability and eliminates horizontal scrolling.
In addition it sorts the classes logically, removes unnecessary whitespaces and duplicate classes and groups the classes by their variants. It works in jsx, svelte, vue, and html files.

Buy me a coffee | GitHub Sponsors

This project is financed by the community.
If you or your company benefit from this project, please consider becoming a sponsor or making a one-time donation.
Your contribution will help me to maintain and develop the project.

Installation

npm i -D eslint-plugin-readable-tailwind

Quick start

• Follow the Parsers section below to learn how to configure the plugin for your specific requirements.
• Read the Rules section to learn about the available rules and how to configure them.
• Configure your editor to conveniently auto-fix on save.

Parsers

Depending on the flavor you are using, you may need to install and configure the corresponding parser:

• JSX (React, Solid.js, Qwik)
• TSX (React, Solid.js, Qwik) with TypeScript support
• Svelte
• Vue
• HTML
• Plain JavaScript
• Plain TypeScript

Rules

Two predefined configurations are available that contain the recommended rules:

• error - will throw an error if the rule is violated
• warning - will throw a warning if the rule is violated

The following table shows the available rules and if they are enabled by default in the different configurations:

Name	Description	error	warning	autofix
multiline	Enforce consistent line wrapping for tailwind classes.	✔	✔	✔
no-unnecessary-whitespace	Disallow unnecessary whitespace in tailwind classes.	✔	✔	✔
sort-classes	Enforce a consistent order for tailwind classes.	✔	✔	✔
no-duplicate-classes	Remove duplicate classes.	✔	✔	✔

Utilities

This plugin works out of the box with most popular tailwind utilities:

• tailwind merge
• class variance authority
• tailwind variants
• shadcn
• classcat
• class list builder
• clsx
• cnbuilder
• classnames template literals
• obj str

In case an utility is not supported or you have built your own, you can change which literals will get linted for each rule. Read the API documentation to learn how to override or extend the default config.

Editor configuration

VSCode

Auto-fix on save

All rules are intended to automatically fix the tailwind classes. If you have installed the VSCode ESLint plugin, you can configure it to automatically fix the classes on save by adding the following options to your .vscode/settings.json:

{
  // enable ESLint to fix tailwind classes on save
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

Changelog

v2.0.0

Adds tailwindcss v4 support while keeping support for tailwindcss v3. (#78)

This version contains breaking changes. Most notably support for Node.js < 20 had to be dropped. The other breaking changes are mostly just changes of the default config, that may cause linting errors.

Migration

• If you use tailwindcss v4, you should specify the entryPoint of the css based tailwind configuration file for the sort-classes rule or in the settings.

• If you have customized the classAttributes option for any of the rules or via the settings, rename the option to attributes

• If you have customized attributes, callees, variables, or tags, escape any reserved characters for regular expressions in the name as the name is now evaluated as a regular expression.

  For example:

   {
     variables: [
  -    "$MyVariable"
  +    "\\$MyVariable"
     ]
   }
  

Changes

• Reload tailwind config automatically if a change is detected.
• Options now correctly override settings (#66)

⚠️ Breaking Changes

• ⚠️ Drop support for Node.js < 20 due to incompatibility of worker threads.
• ⚠️ Add support for tailwindcss v4 (#25)
  • The official class ordering seems to have changed slightly.
  • The improved sorting order will no longer sort variants alphabetically, instead it just makes sure that identical variants are grouped together.
• ⚠️ Regex names (#63)
  • "Names" can now be regular expressions. This is a breaking change, if you have names configured that contain reserved characters in regular expressions like $.
• ⚠️ Enable no-duplicate-classes by default (#67)
• ⚠️ Change default multiline grouping to newLine (#68)
• ⚠️ Rename classAttributes to attributes (#69)