eslint-plugin-tailwindcss

What is eslint-plugin-tailwindcss?

eslint-plugin-tailwindcss is an ESLint plugin that provides linting rules for Tailwind CSS classes. It helps ensure that Tailwind CSS classes are used correctly and consistently in your project.

What are eslint-plugin-tailwindcss's main functionalities?

Class Order

This feature ensures that Tailwind CSS classes are ordered correctly. It helps maintain a consistent order of classes, which can improve readability and maintainability.

module.exports = {
  plugins: ['tailwindcss'],
  rules: {
    'tailwindcss/classnames-order': 'warn'
  }
};

No Custom Classnames

This feature disallows the use of custom class names that are not part of the Tailwind CSS framework. It ensures that only Tailwind CSS classes are used, which can help prevent styling issues.

module.exports = {
  plugins: ['tailwindcss'],
  rules: {
    'tailwindcss/no-custom-classname': 'error'
  }
};

No Arbitrary Value

This feature disallows the use of arbitrary values in Tailwind CSS classes. It ensures that only predefined values are used, which can help maintain consistency and prevent errors.

module.exports = {
  plugins: ['tailwindcss'],
  rules: {
    'tailwindcss/no-arbitrary-value': 'error'
  }
};

Other packages similar to eslint-plugin-tailwindcss

eslint-plugin-css-modules

eslint-plugin-css-modules is an ESLint plugin that provides linting rules for CSS Modules. It helps ensure that CSS Modules are used correctly and consistently in your project. Unlike eslint-plugin-tailwindcss, which focuses on Tailwind CSS, eslint-plugin-css-modules is designed for projects using CSS Modules.

stylelint

stylelint is a powerful, modern linter that helps you avoid errors and enforce conventions in your styles. While eslint-plugin-tailwindcss is specifically for Tailwind CSS, stylelint can be used with any CSS framework or custom CSS. It offers a wide range of rules and is highly configurable.

eslint-plugin-styled-components-a11y

eslint-plugin-styled-components-a11y is an ESLint plugin that provides accessibility linting rules for styled-components. It helps ensure that styled-components are used in an accessible way. While eslint-plugin-tailwindcss focuses on Tailwind CSS, eslint-plugin-styled-components-a11y is designed for projects using styled-components.

README

eslint-plugin-tailwindcss

Rules enforcing best practices and consistency using Tailwind CSS

🎉 The version 3 of plugin is now ready for TailwindCSS v3 🎉

Make sure to use the correct version

• Still using TailwindCSS v2 ?
  • You should stick with v1.x.x or v2.x.x of this plugin (next support releases will be using major version 2)
• Using TailwindCSS v3 ?
  • Make sure to use v3.x.x of this plugin

We need you ❤️

Version 3 of the plugin is brand new and you will most likely experience bugs, please provide feedback by opening issues on GitHub with all the useful informations so that we can fix them all.

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

• New rule: migration-from-tailwind-2 for easy migration from TailwindCSS v2 to v3

• Support for TailwindCSS v3

  • New config matching the updated docs
  • Support for arbitrary properties

• groupByResponsive is enabled by default for classnames-order

View all releases on github

Monthly sponsors

One-time sponsors

TheoBr sponsorship gave me a little extra motivation. Thanks, man

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:])
• migration-from-tailwind-2 for easy upgrade from TailwindCSS v2 to v3
• 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.

Installation

You'll first need to install ESLint:

$ npm i eslint --save-dev

Next, install eslint-plugin-tailwindcss:

$ npm i eslint-plugin-tailwindcss --save-dev

Add tailwindcss to the plugins section of your .eslintrc configuration file. You can omit the eslint-plugin- prefix:

{
  "plugins": ["tailwindcss"]
}

Configuration

Use our preset to get reasonable defaults:

  "extends": [
    "plugin:tailwindcss/recommended"
  ]

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

Configure the rules you want to use under the rules section.

The following lines are matching the configuration saved in the recommended preset...

{
  "rules": {
    "tailwindcss/classnames-order": "warn",
    "tailwindcss/migration-from-tailwind-2": "warn",
    "tailwindcss/no-custom-classname": "warn",
    "tailwindcss/no-contradicting-classname": "error"
  }
}

Learn more about Configuring Rules in ESLint.

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"],
      "groupByResponsive": false,
      "groups": defaultGroups, // imported from groups.js
      "prependCustom": false,
      "removeDuplicates": true,
      "whitelist": []
    }
  }
}

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

• enforces-shorthand: Make sure you group properties inside a shorthand when possible e.g. mx-5 my-5 should become m-5

• 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.

Alternatives

I wrote this plugin after searching for existing tools which perform the same task but didn't satisfied my needs:

• eslint-plugin-tailwind, not bad but no support (yet) for variants sorting
• Headwind, only works within Visual Studio Code

Contributing

You are welcome to contribute to this project by reporting issues, feature requests or even opening Pull Requests.

Learn more about contributing to ESLint-plugin-TailwindCSS.