eslint-plugin-tailwindcss

eslint-plugin-tailwindcss is a set of ESLint rules purpose-built for projects using Tailwind CSS v4. Rather than leaving classname hygiene to code review, it plugs directly into the ESLint flat config pipeline and calls the real Tailwind CSS compiler (via a synchronous worker built on synckit) to check whether classnames are valid, canonical, contradictory, or could be written more concisely.

The plugin ships nine rules covering classname ordering, canonical spelling, shorthand enforcement, arbitrary-value usage, and contradiction detection, with several auto-fixable via --fix. Because it parses classnames out of JSX/TSX attributes, template literals, and utility functions like clsx, cva, and tw, it works across React, Vue, Svelte, and Angular templates rather than being tied to one framework.

What You Get

• Nine rules covering classname ordering, canonical spelling, shorthand enforcement, negative-value formatting, and contradiction detection
• Auto-fix support (--fix) for the rules that can be mechanically corrected, plus editor-suggestion fixes for the rest
• A recommended flat-config preset that enables sensible defaults out of the box
• Real Tailwind CSS v4 compiler integration via a synchronous worker, so validity checks reflect the actual resolved theme rather than a hardcoded utility list
• Configurable attribute and function scanning (class, className, clsx, cva, tw, twMerge, and more) so classnames are found wherever they’re written, not just in a class attribute
• Framework-agnostic parsing across React/JSX, Vue, Svelte, and Angular templates

Common Use Cases

• Enforcing a consistent, deterministic classname order across a team so diffs stay clean and reviewable
• Catching contradicting utility classes (e.g. flex and hidden fighting for the same property) before they ship
• Flagging custom, non-Tailwind classnames that snuck into a className prop by mistake
• Running as a CI/pre-merge check so Tailwind class hygiene doesn’t rely on manual review
• Simplifying verbose multi-class combinations into Tailwind’s built-in shorthand utilities automatically

Under The Hood

Architecture

The plugin is organized as a standard ESLint flat-config plugin object (src/index.ts) that registers nine independent rule modules under src/rules/, each exporting a rule name and an ESLint rule object built on @typescript-eslint/utils. Classname extraction is centralized in src/utils/parser/ (classname, groups, node, and visitor modules) so every rule shares the same logic for locating classnames inside JSX attributes, template literals, and utility-function calls rather than re-implementing extraction per rule. The most consequential architectural choice is src/utils/tailwindcss-api/index.ts, which offloads calls into the real Tailwind CSS v4 compiler to a worker thread via synckit’s createSyncFn, exposing it to ESLint’s synchronous rule API through a small in-memory cache (theme, sorted classnames, validity, class properties) with size- and age-based eviction — this is what lets rules make compiler-accurate decisions without ESLint having to go async.

Tech Stack

Written in TypeScript and built with unbuild, targeting Node 20.19+ and ESLint 9/10 via @typescript-eslint/utils’s flat-config types. It depends on postcss and postcss-nested for CSS parsing, tailwind-api-utils and a bundled worker script for talking to the real Tailwind compiler, and synckit to bridge that async compiler API into ESLint’s synchronous rule execution model. Framework-specific parsing is handled through peer parsers pulled in as dev/test dependencies only when needed (vue-eslint-parser, svelte-eslint-parser, @angular-eslint/template-parser).

Code Quality

Test coverage is extensive and co-located: nearly every rule and utility file under src/ has a matching .spec.ts file, and several performance-sensitive utilities (enforces-shorthand, get-theme-key-prefixes-from-classname) also have .bench.ts benchmark files, run via Vitest. CI (.github/workflows) runs pnpm run lint and pnpm run test on every push. The project dogfoods eslint-plugin-eslint-plugin and eslint-plugin-unicorn on its own source, and rules are fully typed against ESLint’s flat-config Rule types rather than using loosely-typed rule objects.

API Design The public surface is intentionally small: install the plugin, spread the recommended config, and set one required setting (cssConfigPath) pointing at the project’s Tailwind CSS file. A typed PluginSettings export gives editors autocomplete and validation on the settings object via JSDoc @type annotations, and sensible defaults exist for every other setting (which attributes/functions to scan, cache size/age) so most projects only ever touch the one mandatory field.