@yorganci/eslint-plugin-tailwindcss

ESLint plugin for enforcing best practices while using Tailwind CSS.

Installation

# Using npm
npm install --save-dev @yorganci/eslint-plugin-tailwindcss
# Using yarn
yarn add --dev @yorganci/eslint-plugin-tailwindcss
# Using pnpm
pnpm add --save-dev @yorganci/eslint-plugin-tailwindcss
# Using bun
bun add --dev @yorganci/eslint-plugin-tailwindcss

Quick Start

The plugin provides two configurations tailwindcss.configs.recommended and tailwindcss.configs.strict. Recommended rules only add warnings are less opinionated, while strict config enables most of the rules.

import tailwindcss from "@yorganci/eslint-plugin-tailwindcss";
import { defineConfig } from "eslint/config";

export default defineConfig([
	// ...
	tailwindcss.configs.recommended,
	{
		settings: {
			tailwindcss: {
				stylesheet: "path/to/tailwind/stylesheet.css",
			}
		}
	}
]);

Rules Overview

| Rule | Description | Type | Recommended | Fixable | | ----------------------------------------- | ------------------------------------------------------------------------------- | ---------------- | ----------- | ------- | | classname-order | Enforce consistent order of the TailwindCSS classes. | Possible Errors | ✅ | ✅ | | no-arbitrary-value | Disallow using arbitrary values in classnames. | Stylistic Issues | ❌ | ❌ | | no-contradicting-classnames | Disallow contradicting Tailwind CSS classnames (e.g. "w-3 w-5"). | Possible Errors | ✅ | ❌ | | no-custom-classname | Disallow custom classnames not included in Tailwind CSS. | Stylistic Issues | ❌ | ❌ | | no-duplicate-classnames | Disallow duplicate Tailwind CSS classnames. | Best Practices | ✅ | ✅ | | no-irregular-whitespace | Disallow redundant whitespace in CSS class name expressions. | Best Practices | ✅ | ✅ | | no-unnecessary-arbitrary-value | Disallow using arbitrary values in classnames when an equivalent preset exists. | Best Practices | ✅ | ✅ | | no-unnecessary-negative-arbitrary-value | Disallow unnecessary negative arbitrary values when alternative exists. | Stylistic Issues | ❌ | ✅ | | shorthand | Enforce usage of shorthand Tailwind CSS classname. | Best Practices | ✅ | ✅ |

• classname-order classes should appear in the same order they are generated by Tailwind, CSS applies classes based on the position they appear in the sources code. Thus, mismatch between classname order in JSX attribute and Tailwind can cause hard to debug errors.

Settings

The plugin supports the following settings.

import tailwindcss from "@yorganci/eslint-plugin-tailwindcss";
import { defineConfig } from "eslint/config";

export default defineConfig([
	// ...
	tailwindcss.configs.recommended,
	{
		settings: {
			tailwindcss: {
				// Path to CSS file with `@import "tailwindcss";` directive.
				stylesheet: "path/to/tailwind/stylesheet.css",
				// Regex to match attribute names in JSX
				attributeRegex: "^class(?:Name)?$",
				// List of class functions to check for class names.
				classFunctions: ["cc", "clb", "clsx", "cn", "cnb", "ctl", "cva", "cx", "dcnb", "objstr", "tv", "twJoin", "twMerge"],
				// List of tags to check for class names, tw`block text-red`
				tags: ["tw"],
				// Regex to match variable names, `const styles = "..."`
				variableRegex: "^.*(styles|classNames)$",
			}
		}
	}
]);

• stylesheet: Path to your Tailwind CSS stylesheet
• classRegex: Regular expression to match class attributes (default: ^class(?:Name)?$)

Requirements

• Node.js >= 18.12.0
• ESLint >= 9.0.0
• Tailwind CSS >= 4.0.0

Credits

• Forked from @francoismassart original author of eslint-plugin-tailwindcss package.
• @dcastil author of tailwind-merge package for resolving and finding conflicts.
• prettier-plugin-tailwindcss contributors for classname order.
• @schoreo author of eslint-plugin-better-tailwindcss for reference synckit and settings schema.
• @atahanyorganci for updating package to Tailwind CSS v4.

License

This project is licensed under the MIT License.

This project also partially contains code derived or copied from the following projects:

• prettier-plugin-tailwindcss MIT
• tailwind-merge MIT