eslint-plugin-tailwind-canonical-classes weekly downloads statistics

eslint-plugin-tailwind-canonical-classes

ESLint plugin to enforce canonical Tailwind CSS class names using Tailwind CSS v4's canonicalization API.

📋 Table of Contents

• Features
• Comparison
• Installation
• Quick Start
• Configuration
• Options
• Usage Examples
• How It Works
• Limitations
• Troubleshooting
• Contributing
• License
• Related Links

✨ Features

• 🔍 Automatic Detection: Automatically detects non-canonical Tailwind CSS class names in JSX/TSX, Svelte, and Vue files
• 🔧 Auto-fix Support: Automatically fixes non-canonical classes using ESLint's auto-fix feature
• 🎯 Tailwind CSS v4 Integration: Uses Tailwind CSS v4's official canonicalizeCandidates API
• 📝 Multiple Format Support: Works with string literals, template literals, ternaries, &&/||, arrays, and object keys
• 🛠️ Utility Function Support: Detects and fixes classes in utility functions like cn(), clsx(), classNames(), twMerge(), cva(), and tv(), and in tw`…` tagged templates
• ⚡ Zero Config: Minimal configuration required to get started

⚖️ Comparison

Two larger plugins also ship a canonical-classes rule built on the same Tailwind API: eslint-plugin-tailwindcss (enforces-canonical-classname) and eslint-plugin-better-tailwindcss (enforce-canonical-classes). Choose this plugin when you want only canonical class names, with no other Tailwind rules to configure.

	This plugin	eslint-plugin-tailwindcss	eslint-plugin-better-tailwindcss
Scope	Canonical classes only	Full Tailwind rule set	Full Tailwind rule set
px → spacing scale (p-[16px] → p-4)	On by default	No	With rootFontSize
Two classes with the same canonical form (p-[1rem] p-4)	Fixes only p-[1rem]	Rewrites the wrong classes	Not reported
Rule time, 400 JSX files, 12k class strings, first run	1.2 s	1.2 s	9.8 s
Same, next runs (on-disk cache)	0.1 s	1.2 s	9.8 s
Ternaries, template literals with ${}, clsx object keys, Vue :class object/array bindings	Checked	Checked	Checked
cva variants, tv(), tw`…` tagged templates	Checked	Checked	Checked

Measured on 2026-10-20 with ESLint 9.39, Tailwind CSS 4.3.3, eslint-plugin-tailwindcss 4.4.0, and eslint-plugin-better-tailwindcss 4.10.0. Rule time is total lint time minus a run with the rule off, median of five runs.

📦 Installation

Install the plugin and its peer dependency:

npm install --save-dev eslint-plugin-tailwind-canonical-classes @tailwindcss/node

Or with yarn:

yarn add -D eslint-plugin-tailwind-canonical-classes @tailwindcss/node

Or with pnpm:

pnpm add -D eslint-plugin-tailwind-canonical-classes @tailwindcss/node

Requirements

• Node.js >= 18.0.0
• ESLint 8, 9, or 10
• Tailwind CSS v4
• @tailwindcss/node package
• svelte-eslint-parser (optional, required for Svelte support)
• vue-eslint-parser (optional, required for Vue support)

ESLint Version Compatibility

ESLint Version	Flat Config (eslint.config.*)	Legacy Config (.eslintrc.*)
8.x	Supported	Supported
9.x	Supported	Supported
10.x	Supported	Not available (removed by ESLint)

Note: ESLint 10 removes .eslintrc support entirely. If you are upgrading to ESLint 10, you must migrate to flat config.

🚀 Quick Start

1. Install the plugin (see Installation)

2. Add to your ESLint config (eslint.config.mjs):

   import tailwindCanonicalClasses from 'eslint-plugin-tailwind-canonical-classes';
   
   export default [
     ...tailwindCanonicalClasses.configs['flat/recommended'],
     {
       rules: {
         'tailwind-canonical-classes/tailwind-canonical-classes': [
           'warn',
           {
             cssPath: './app/styles/globals.css',
           },
         ],
       },
     },
   ];
   

3. Run ESLint:

   npx eslint . --fix
   

⚙️ Configuration

Flat Config (ESLint 8+) — Recommended

Using the built-in flat/recommended config:

import tailwindCanonicalClasses from 'eslint-plugin-tailwind-canonical-classes';

export default [
  ...tailwindCanonicalClasses.configs['flat/recommended'],
  {
    rules: {
      'tailwind-canonical-classes/tailwind-canonical-classes': [
        'warn', // or 'error'
        {
          cssPath: './app/styles/globals.css', // Required
          rootFontSize: 16, // Optional, default: 16
          calleeFunctions: ['cn', 'clsx'], // Optional, default: ['cn', 'clsx', 'classNames', 'twMerge', 'cva', 'tv', 'tw']
        },
      ],
    },
  },
];

Svelte (Flat Config)

Install the Svelte parser alongside the plugin:

npm install --save-dev svelte-eslint-parser

Then extend the built-in config:…