Awesome
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 for consistency and it makes merge conflict a bit easier to resolveenforces-negative-arbitrary-values
: make sure to use negative arbitrary values classname without the negative classname e.g.-top-[5px]
should becometop-[-5px]
enforces-shorthand
: merge multiple classnames into shorthand if possible e.g.mx-5 my-5
should becomem-5
migration-from-tailwind-2
for easy upgrade from Tailwind CSSv2
tov3
. Warning: at the moment you should temporary turn off theno-custom-classname
rule if you want to see the warning frommigration-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 thewhitelist
optionno-contradicting-classname
: e.g. avoidp-2 p-3
, different Tailwind CSS classnames (pt-2
&pt-3
) but targeting the same property several times for the same variant.no-unnecessary-arbitrary-value
: e.g. replacingm-[1.25rem]
by its configuration based classnamem-5
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
🥰 How you can support us? | 💪 They did it! |
---|---|
Premium Sponsors <br /> Support us by becoming a sponsor. <br /> Become a recurring sponsor | <a href="https://daily.dev/" target="_blank"><img width="150" src="https://raw.githubusercontent.com/francoismassart/eslint-plugin-tailwindcss/master/sponsors/daily.dev.jpg"></a> |
Current Sponsors <br /> Any amount is appreciated. | <a href="https://github.com/jonz94" target="_blank"><img src="https://avatars.githubusercontent.com/u/16042676?s=150&v=4" width="75" height="75" style="border-radius:100%;" alt="@jonz94"></a> <a href="https://github.com/theMosaad" target="_blank"><img src="https://avatars.githubusercontent.com/u/48773133?s=150&v=4" width="75" height="75" style="border-radius:100%;" alt="@theMosaad"></a> <a href="https://github.com/acewf" target="_blank"><img src="https://avatars.githubusercontent.com/u/4835572?s=150&v=4" width="75" height="75" style="border-radius:100%;" alt="@acewf"></a> <a href="https://github.com/charkour" target="_blank"><img src="https://avatars.githubusercontent.com/u/33156025?s=150&v=4" width="75" height="75" style="border-radius:100%;" alt="@charkour"></a> <a href="https://github.com/dailydotdev" target="_blank"><img class="avatar" src="https://avatars.githubusercontent.com/u/41463883?s=150&v=4" width="75" height="75" style="border-radius:100%;" alt="@dailydotdev"></a> <a href="https://github.com/codecov" target="_blank"><img class="avatar" src="https://avatars.githubusercontent.com/u/8226205?s=150&v=4" width="75" height="75" style="border-radius:100%;" alt="@codecov"></a> <a href="https://github.com/sourcegraph" target="_blank"><img class="avatar" src="https://avatars.githubusercontent.com/u/3979584?s=150&v=4" width="75" height="75" style="border-radius:100%;" alt="@sourcegraph"></a> |
Past sponsors <br /> Even if this is just a one-time thing. <br /> Become a backer | <a href="https://github.com/aniravi24" target="_blank"><img src="https://avatars.githubusercontent.com/u/5902976?s=100&v=4" width="50" height="50" style="border-radius:100%;" alt="@aniravi24"></a> <a href="https://github.com/mongolyy" target="_blank"><img src="https://avatars.githubusercontent.com/u/10972787?s=100&v=4" width="50" height="50" style="border-radius:100%;" alt="@mongolyy"></a> <a href="https://github.com/t3dotgg" target="_blank"><img src="https://avatars.githubusercontent.com/u/6751787?s=100&v=4" width="50" height="50" style="border-radius:100%;" alt="@t3dotgg"></a> |
Contributors <br /> This project can evolve thanks to all the people who contribute. <br /> You are welcome to contribute to this project by reporting issues, feature requests or even opening Pull Requests. | <a href="https://github.com/francoismassart/eslint-plugin-tailwindcss/graphs/contributors"><img src="https://contrib.rocks/image?repo=francoismassart/eslint-plugin-tailwindcss&width=300&columns=4" /></a> |
Supporters <br /> Talk about the plugin on your social networks | <a href="https://twitter.com/search?q=eslint-plugin-tailwindcss&src=recent_search_click" target="_blank">eslint-plugin-tailwindcss on Twitter</a> |
Latest changelog
- fix: config loading cache
- fix: Avoid re-parsing unchanged CSS files
- fix: AST expression tests for null expressions (by kesor 🙏)
- fix:
no-arbitrary-value
rule is too broad - fix: support
tag.div
andtag(Component)
(by nihalgonsalves 🙏) - feat: support flat config and ESLint 9 (by kazupon 🙏)
- feat: new rule
no-unnecessary-arbitrary-value
🎉 - fix: retro compatibility for older Tailwind CSS (before typescript config)
- fix: composable touch action classnames
- fix:
shadow-md
+shadow-[#color]
can be used together 🤝 - fix:
tabular-nums
andslashed-zero
can be used together 🤝 - fix:
size-*
basedsize
,spacing
,width
andheight
🤓 - fix: there is no
size-screen
😅 - fix: edge cases with whitespace in
enforces-shorthand
(by kachkaev 🙏) - fix: parsing spreads in function call returns(by egorpavlikhin 🙏)
- feat: support for Tailwind CSS 3.4.0
- ci: add github actions workflow (by nihalgonsalves 🙏)
- fix: bg-center mark as conflicting with bg-[image:xxx]
- feat: support enforcing truncate shorthand (by bezbac 🙏)
- fix: parsing spreads in object expressions (by bezbac 🙏)
- fix: do not handle non-ASCII whitespace as separator (by uhyo 🙏)
- fix: prefix support for named group/peer syntax (by bezbac 🙏)
- feat: support tailwind config in typescript (by quesabe 🙏)
You may have to upgrade your Tailwind CSS version to
3.3.2
Screencasts on our YouTube Channel
<a href="https://www.youtube.com/@eslint-plugin-tailwind-css"><img src=".github/youtube-eslint-plugin-tailwindcss-round.png" width="80" height="80" alt="YouTube Channel" /></a> | <span style="font-size:18px">ESLint plugin Tailwind CSS</span><br>youtube.com/@eslint-plugin-tailwindcss |
---|
Installation
1. Install eslint
and eslint-plugin-tailwindcss
You'll first need to install ESLint:
$ npm i -D eslint eslint-plugin-tailwindcss
2. Create Configuration file
.eslintrc
Use .eslintrc.* file to configure rules in ESLint < v9. See also: https://eslint.org/docs/latest/use/configure/.
module.exports = {
root: true,
extends: ["plugin:tailwindcss/recommended"],
};
If you would like to know about configuration, Learn more in ESLint docs
eslint.config.js
Use eslint.config.js
file to configure rules. This is the default in ESLint v9, but can be used starting from ESLint v8.57.0. See also: https://eslint.org/docs/latest/use/configure/configuration-files-new.
import tailwind from "eslint-plugin-tailwindcss";
export default [...tailwind.configs["flat/recommended"]];
If you would like to know about configuration, Learn more in ESLint docs
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 .eslintrc
- 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', }, ],
- Install the 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', }, ],
- Install the 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', }, ],
- Install the 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.
For eslint.config.js
-
For
js[x]
,ts[x]
:-
Install the parser:
npm i -D @eslint/js typescript-eslint
-
Assign it to your files in
eslint.config.js
:import js from "@eslint/js"; import ts from "typescript-eslint"; import tailwind from "eslint-plugin-tailwindcss"; export default [ // add eslint built-in js.configs.recommended, // add `typescript-eslint` flat config simply // if you would like use more another configuration, // see the section: https://typescript-eslint.io/getting-started#details ...ts.configs.recommended, ...tailwind.configs["flat/recommended"], ];
-
-
For
vue.js
:-
Install the parser:
npm i -D eslint-plugin-vue
-
Assign it to your files in
eslint.config.js
:import vue from "eslint-plugin-vue"; import tailwind from "eslint-plugin-tailwindcss"; export default [ // add `eslint-plugin-vue` flat config simply // if you would like use more another configuration, // see the section: https://eslint.vuejs.org/user-guide/#bundle-configurations-eslint-config-js ...vue.configs["flat/recommended"], ...tailwind.configs["flat/recommended"], ];
-
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.
For .eslintrc
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`
},
},
}
For eslint.config.js
import tailwind from "eslint-plugin-tailwindcss";
export default [
...tailwind.configs["flat/recommended"],
{
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:
- In the rule option argument (rule level)
- In the shared settings (plugin level)
- 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. avoidmx-5 sm:mx-5
, no need to redefinemx
insm:
variant as it uses the same value (5
) -
only-valid-arbitrary-values
:- e.g. avoid
top-[42]
, only0
value can be unitless. - e.g. avoid
text-[rgba(10%,20%,30,50%)]
, can't mix%
and0-255
.
- e.g. avoid