eslint-plugin-better-tailwindcss/README.md

auto-wraps tailwind classes after a certain print width or class count into multiple lines to improve readability.

<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="./assets/eslint-plugin-better-tailwindcss-logo-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="./assets/eslint-plugin-better-tailwindcss-logo-light.svg">
    <img alt="eslint-plugin-better-tailwindcss logo" src="./assets/eslint-plugin-better-tailwindcss-logo.svg">
  </picture>
</div>

<h1 align="center">eslint-plugin-better-tailwindcss</h1>

<br/>
<br/>

<div align="center">
  <a alt="GitHub license" href="https://github.com/schoero/eslint-plugin-better-tailwindcss/blob/main/LICENSE"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/license/schoero/eslint-plugin-better-tailwindcss?style=flat-square&labelColor=32363B&color=ffffff" /><source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/license/schoero/eslint-plugin-better-tailwindcss?style=flat-square&labelColor=EBEEF2&color=000000" /><img alt="eslint-plugin-better-tailwindcss logo" src="https://img.shields.io/github/license/schoero/eslint-plugin-better-tailwindcss?style=flat-square&labelColor=EBEEF2&color=000000" /></picture></a>
  <a alt="npm version" href="https://www.npmjs.com/package/eslint-plugin-better-tailwindcss?activeTab=versions"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/v/eslint-plugin-better-tailwindcss?style=flat-square&labelColor=32363B&color=ffffff" /><source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/npm/v/eslint-plugin-better-tailwindcss?style=flat-square&labelColor=EBEEF2&color=000000" /><img alt="eslint-plugin-better-tailwindcss logo" src="https://img.shields.io/npm/v/eslint-plugin-better-tailwindcss?style=flat-square&labelColor=EBEEF2&color=000000" /></picture></a>
  <a alt="GitHub issues" href="https://github.com/schoero/eslint-plugin-better-tailwindcss/issues"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/issues/schoero/eslint-plugin-better-tailwindcss?style=flat-square&labelColor=32363B&color=ffffff" /><source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/issues/schoero/eslint-plugin-better-tailwindcss?style=flat-square&labelColor=EBEEF2&color=000000" /><img alt="eslint-plugin-better-tailwindcss logo" src="https://img.shields.io/github/issues/schoero/eslint-plugin-better-tailwindcss?style=flat-square&labelColor=EBEEF2&color=000000" /></picture></a>
  <a alt="npm total downloads" href="https://www.npmjs.com/package/eslint-plugin-better-tailwindcss?activeTab=readme"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/dt/eslint-plugin-better-tailwindcss?style=flat-square&labelColor=32363B&color=ffffff" /><source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/npm/dt/eslint-plugin-better-tailwindcss?style=flat-square&labelColor=EBEEF2&color=000000" /><img alt="eslint-plugin-better-tailwindcss logo" src="https://img.shields.io/npm/dt/eslint-plugin-better-tailwindcss?style=flat-square&labelColor=EBEEF2&color=000000" /></picture></a>
  <a alt="GitHub repo stars" href="https://github.com/schoero/eslint-plugin-better-tailwindcss/stargazers"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/stars/schoero/eslint-plugin-better-tailwindcss?style=flat-square&labelColor=32363B&color=ffffff" /><source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/stars/schoero/eslint-plugin-better-tailwindcss?style=flat-square&labelColor=EBEEF2&color=000000" /><img alt="eslint-plugin-better-tailwindcss logo" src="https://img.shields.io/github/stars/schoero/eslint-plugin-better-tailwindcss?style=flat-square&labelColor=EBEEF2&color=000000"/></picture></a>
  <a alt="GitHub sponsors" href="https://github.com/sponsors/schoero"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/sponsors/schoero?style=flat-square&labelColor=32363B&color=ffffff" /><source media="(prefers-color-scheme: light)" srcset="hhttps://img.shields.io/github/sponsors/schoero?style=flat-square&labelColor=EBEEF2&color=000000" /><img alt="eslint-plugin-better-tailwindcss logo" src="https://img.shields.io/github/sponsors/schoero?style=flat-square&labelColor=EBEEF2&color=000000" /></picture></a>
</div>

<br/>
<br/>

ESLint plugin with formatting and linting rules to help you write cleaner, more maintainable Tailwind CSS.  

The formatting rules focus on improving readability by automatically breaking up long Tailwind class strings into multiple lines and sorting/grouping them in a logical order. The linting rules enforce best practices and catch potential issues, ensuring that you're writing valid Tailwind CSS.  

This plugin supports a wide range of projects, including React, Solid.js, Qwik, Svelte, Vue, Astro, Angular, HTML or plain JavaScript or TypeScript.  

<br/>
<br/>

<div align="center">
  <img alt="eslint-plugin-better-tailwindcss example" width="640px" src="./assets/eslint-plugin-better-tailwindcss-demo.png">
</div>

<br/>
<br/>

<div align="center">

  <a href="https://github.com/sponsors/schoero">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="./assets/sponsor-dark.svg">
      <source media="(prefers-color-scheme: light)" srcset="./assets/sponsor-light.svg">
      <img alt="eslint-plugin-better-tailwindcss logo" src="./assets/sponsor-light.svg">
    </picture>
  </a>
  
  <br/>
  <br/>
  
  [Buy me a coffee](https://buymeacoffee.com/schoero) | [GitHub Sponsors](https://github.com/sponsors/schoero)
  
  Help support this project.  
  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.

</div>

<br/>
<br/>

## Installation

```sh
npm i -D eslint-plugin-better-tailwindcss
```

<br/>

## Quick start

1. Follow the [parsers](#parsers) section below to learn how to configure the plugin for your specific requirements.

1. Configure the plugin to be able to read your tailwind configuration via [settings](docs/settings/settings.md) or for each [rule](#rules) separately.

    ```jsonc
    // eslint.config.js
    {
      //...
      "settings": {
        "better-tailwindcss": {
          // tailwindcss 4: the path to the entry file of the css based tailwind config (eg: `src/global.css`)
          "entryPoint": "src/global.css",
          // tailwindcss 3: the path to the tailwind config file (eg: `tailwind.config.js`)
          "tailwindConfig": "tailwind.config.js"
        }
      }
    }
    ```

1. Configure your editor to conveniently [auto-fix on save](#auto-fix-on-save).

<br/>
<br/>

### Parsers

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

- [JSX (React, Solid.js, Qwik)](docs/parsers/jsx.md)
- [TSX (React, Solid.js, Qwik) with TypeScript support](docs/parsers/tsx.md)
- [Svelte](docs/parsers/svelte.md)
- [Vue](docs/parsers/vue.md)
- [Astro](docs/parsers/astro.md)
- [Angular](docs/parsers/angular.md)
- [HTML](docs/parsers/html.md)
- [Plain JavaScript](docs/parsers/javascript.md)
- [Plain TypeScript](docs/parsers/typescript.md)

<br/>
<br/>

### Rules

The rules are categorized into two types: `stylistic` and `correctness`.

#### Configs

The plugin offers three recommended configurations to help you get started quickly:
  
- `stylistic`: Enforces stylistic rules for tailwind classes.
- `correctness`: Enforces correctness rules for tailwind classes.
- `recommended`: Enforces both stylistic and correctness rules.
  
By default:

- `stylistic` rules are reported as warnings
- `correctness` rules are reported as errors
  
You can change the severity by adding a suffix to the config name:
  
- Use `-error` to report all rules as errors
- Use `-warn` to report all rules as warnings
  
For example, `recommended-warn` will report every rule as a warning and `stylistic-error` will report the formatting rules as errors.
  
The table below lists all available rules, the Tailwind CSS versions they support, and whether they are enabled by default in each recommended configuration:

<br/>
<br/>

#### Stylistic rules

| Name | Description | `tw3` | `tw4` | `recommended` | autofix |
| :--- | :--- | :---: | :---: | :---: | :---: |
| [enforce-consistent-line-wrapping](docs/rules/enforce-consistent-line-wrapping.md) | Enforce consistent line wrapping for tailwind classes. | ✔ | ✔ | ✔ | ✔ |
| [enforce-consistent-class-order](docs/rules/enforce-consistent-class-order.md) | Enforce a consistent order for tailwind classes. | ✔ | ✔ | ✔ | ✔ |
| [enforce-consistent-variable-syntax](docs/rules/enforce-consistent-variable-syntax.md) | Enforce consistent variable syntax. | ✔ | ✔ |  | ✔ |
| [enforce-consistent-important-position](docs/rules/enforce-consistent-important-position.md) | Enforce consistent position of the important modifier. | ✔ | ✔ |  | ✔ |
| [enforce-shorthand-classes](docs/rules/enforce-shorthand-classes.md) | Enforce shorthand class names. | ✔ | ✔ |  | ✔ |
| [no-duplicate-classes](docs/rules/no-duplicate-classes.md) | Remove duplicate classes. | ✔ | ✔ | ✔ | ✔ |
| [no-deprecated-classes](docs/rules/no-deprecated-classes.md) | Remove deprecated classes. |  | ✔ |  | ✔ |
| [no-unnecessary-whitespace](docs/rules/no-unnecessary-whitespace.md) | Disallow unnecessary whitespace in tailwind classes. | ✔ | ✔ | ✔ | ✔ |

#### Correctness rules

| Name | Description | `tw3` | `tw4` | `recommended` | autofix |
| :--- | :--- | :---: | :---: | :---: | :---: |
| [no-unregistered-classes](docs/rules/no-unregistered-classes.md) | Report classes not registered with tailwindcss. | ✔ | ✔ | ✔ |  |
| [no-conflicting-classes](docs/rules/no-conflicting-classes.md) | Report classes that produce conflicting styles. |  | ✔ |  |  |
| [no-restricted-classes](docs/rules/no-restricted-classes.md) | Disallow restricted classes. | ✔ | ✔ |  | ✔ |

<br/>
<br/>

### Utilities

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

- [tailwind merge](https://github.com/dcastil/tailwind-merge)
- [class variance authority](https://github.com/joe-bell/cva)
- [tailwind variants](https://github.com/nextui-org/tailwind-variants?tab=readme-ov-file)
- [shadcn](https://ui.shadcn.com/docs/installation/manual)
- [classcat](https://github.com/jorgebucaran/classcat)
- [class list builder](https://github.com/crswll/clb)
- [clsx](https://github.com/lukeed/clsx)
- [cnbuilder](https://github.com/xobotyi/cnbuilder)
- [classnames template literals](https://github.com/netlify/classnames-template-literals)
- [obj str](https://github.com/lukeed/obj-str)

<br/>
<br/>

### Advanced configuration

If an utility is not supported by default, or you want to customize the configuration, you can define which string literals should be linted for each rule.
See the [Advanced configuration guide](./docs/configuration/advanced.md) to learn how to override or extend the default settings.

<br/>
<br/>

### Editor configuration

#### VSCode

##### Auto-fix on save

Most rules are intended to automatically fix the tailwind classes. If you have installed the [VSCode ESLint plugin](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint), you can configure it to automatically fix the classes on save by adding the following options to your `.vscode/settings.json`:

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

<br/>
<br/>