eslint-plugin-tailwindcss

Rules enforcing best practices and consistency using Tailwind CSS.

While you can use the official plugin prettier-plugin-tailwindcss for ordering your classnames...

eslint-plugin-tailwindcss offers more than 5 other rules, that you can benefit from on top of prettier-plugin-tailwindcss. Sounds good ? Keep reading 👇

Supported Rules

Learn more about each supported rules by reading their documentation:

• classnames-order: order classnames by target properties then by variants ([size:][theme:][state:])
• enforces-negative-arbitrary-values: make sure to use negative arbitrary values classname without the negative classname e.g. -top-[5px] should become top-[-5px]
• enforces-shorthand: merge multiple classnames into shorthand if possible e.g. mx-5 my-5 should become m-5
• migration-from-tailwind-2 for easy upgrade from Tailwind CSS v2 to v3. Warning: at the moment you should temporary turn off the no-custom-classname rule if you want to see the warning from migration-from-tailwind-2
• no-arbitrary-value: forbid using arbitrary values in classnames (turned off by default)
• no-custom-classname: only allow classnames from Tailwind CSS and the values from the whitelist option
• no-contradicting-classname: e.g. avoid p-2 p-3, different Tailwind CSS classnames (pt-2 & pt-3) but targeting the same property several times for the same variant.

Using ESLint extension for Visual Studio Code, you will get these messages

You can can the same information on your favorite command line software as well.

🤝 Support eslint-plugin-tailwindcss

Premium Sponsors Support us by becoming a sponsor. Become a recurring sponsor
Current Sponsors Any amount is appreciated.
Past sponsors Even if this is just a one-time thing Become a backer
Contributors This project can evolve thanks to all the people who contribute. You are welcome to contribute to this project by reporting issues, feature requests or even opening Pull Requests.

We need you ❤️

If you enjoy my work you can:

• Share the plugin on Twitter
• Contribute to the project by:
  • Giving feedback
  • Creating an issue
  • Make a pull request
  • Write a feature request
• Give back and sponsor its development

Latest changelog

• fix: default parsers in the recommended preset
• fix: move tailwindcss to peerDependencies (by xeho91 🙏)
• feat: Lint values in a object
• feat: Support for Object syntax in custom callees beside classnames(by dipsaus9 🙏)
• feat: New option skipClassAttribute you can turn on to only lint the callees
• FIX: support for Tailwind CSS version 3.2.3

View all releases on github

Installation

1. Install eslint

You'll first need to install ESLint:

$ npm i -D eslint

Then, create you .eslintrc.js file

module.exports = {
  root: true,
};

2. Install eslint-plugin-tailwindcss

$ npm i -D tailwindcss eslint-plugin-tailwindcss

Edit your .eslintrc file to use our recommended preset to get reasonable defaults:

module.exports = {
  root: true,
  extends: ["plugin:tailwindcss/recommended"],
};

If you do not use our preset you will need to specify individual rules and add extra configuration...

Learn more about Configuring Rules in ESLint.

3. Add a npm script

In your package.json add one or more script(s) to run eslint targeting your source files:

"scripts": {
  "lint": "eslint ./src",
  "lint:debug": "eslint ./src --debug",
  "lint:fix": "eslint ./src --fix"
},

4. Run the linting task

npm run lint can do the job on demand but you can also get live feedback using VS Code ESLint extension, just make sure you restart VS Code as it can be required for the plugin to work as expected.

Optional shared settings

Most rules shares the same settings, instead of duplicating some options...

You should also specify settings that will be shared across all the plugin rules. More about eslint shared settings.

All these settings have nice default values that are explained in each rules' documentation. I'm listing them in the code below just to show them.

{
  settings: {
    tailwindcss: {
      // These are the default values but feel free to customize
      callees: ["classnames", "clsx", "ctl"],
      config: "tailwind.config.js",
      cssFiles: [
        "**/*.css",
        "!**/node_modules",
        "!**/.*",
        "!**/dist",
        "!**/build",
      ],
      cssFilesRefreshRate: 5_000,
      removeDuplicates: true,
      skipClassAttribute: false,
      whitelist: [],
      tags: [],
      classRegex: "^class(Name)?$", // can be modified to support custom attributes. E.g. "^tw$" for `twin.macro`
    },
  },
}

The plugin will look for each setting value in this order and stop looking as soon as it finds the settings:

1. In the rule option argument (rule level)
2. In the shared settings (plugin level)
3. Default value of the requested setting (plugin level)...

Upcoming Rules

• validate-modifiers: I don't know if possible, but I'd like to make sure all the modifiers prefixes of a classname are valid e.g. yolo:bg-red should throw an error...

• no-redundant-variant: e.g. avoid mx-5 sm:mx-5, no need to redefine mx in sm: variant as it uses the same value (5)

• only-valid-arbitrary-values:

  • e.g. avoid top-[42], only 0 value can be unitless.
  • e.g. avoid text-[rgba(10%,20%,30,50%)], can't mix % and 0-255.