/eslint-plugin-tailwindcss

ESLint plugin for Tailwind CSS usage

Primary LanguageJavaScriptMIT LicenseMIT

eslint-plugin-tailwindcss

npm latest version license downloads

eslint-plugin-tailwindcss logo

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:

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

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

🤝 Support eslint-plugin-tailwindcss

🥰 How you can support us? 💪 They did it!
Premium Sponsors
Support us by becoming a sponsor.
Become a recurring sponsor
Current Sponsors
Any amount is appreciated.		 @jonz94 @theMosaad @acewf @charkour @dailydotdev @codecov @sourcegraph
Past sponsors
Even if this is just a one-time thing.
Become a backer		 @aniravi24 @mongolyy @t3dotgg
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.
Supporters
Talk about the plugin on your social networks		 eslint-plugin-tailwindcss on Twitter

Latest changelog

View all releases on github

Screencasts on our YouTube Channel

YouTube Channel ESLint plugin Tailwind CSS
youtube.com/@eslint-plugin-tailwindcss

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 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. Configure ESLint parsers

Depending on the languages you are using in your project you must tell which parser will analyze your source files.

Our recommendations:

  • For js[x], react, ts[x]:
    • Install the parser: npm i -D @typescript-eslint/parser
    • Assign it to your files in eslintrc: 
      overrides: [
  {
    files: ['*.ts', '*.tsx', '*.js'],
    parser: '@typescript-eslint/parser',
  },
],
  • For vue.js:
    • Install the parser: npm i -D vue-eslint-parser
    • Assign it to your files in eslintrc: 
      overrides: [
  {
    files: ['*.vue'],
    parser: 'vue-eslint-parser',
  },
],
  • For HTML and similar:
    • Install the parser: npm i -D @angular-eslint/template-parser
    • Assign it to your files in eslintrc: 
      overrides: [
  {
    files: ['*.html', '*.blade.php'],
    parser: '@angular-eslint/template-parser',
  },
],

We removed the default parsers which were added to v3.8.2 because it created negative impact on dependencies resolution, bundle size increase and possible conflicts with existing configurations.

4. 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"
},

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

More settings

The rules accept settings meant to fit your own choices, make sure to read the documentation of each rule.

Optional shared settings

Most rules share the same settings, instead of duplicating the options all over the place...

You should define the shared settings that will be shared across all the plugin rules.

All these settings already have nice default values that are explained in the documentation.

FYI, here are the default values:

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

The plugin will look for each setting in this order and stops searching 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.

  • no-unnecessary-arbitrary-value: e.g. replacing h-[0] by its configuration based classname h-0.