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
• 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, and JSX expressions
• 🛠️ Utility Function Support: Detects and fixes classes in utility functions like cn(), clsx(), classNames(), twMerge(), and cva()
• ⚡ Zero Config: Minimal configuration required to get started

📦 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']
        },
      ],
    },
  },
];

Svelte (Flat Config)

Install the Svelte parser alongside the plugin:

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

Then extend the built-in config:

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

export default [
  ...tailwindCanonicalClasses.configs['flat/svelte'],
  {
    rules: {
      'tailwind-canonical-classes/tailwind-canonical-classes': [
        'warn',
        {
          cssPath: './src/app.css',
        },
      ],
    },
  },
];

Vue (Flat Config)

Install the Vue parser alongside the plugin:

npm install --save-dev vue-eslint-parser

Then extend the built-in config:

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

export default [
  ...tailwindCanonicalClasses.configs['flat/vue'],
  {
    rules: {
      'tailwind-canonical-classes/tailwind-canonical-classes': [
        'warn',
        {
          cssPath: './src/style.css',
        },
      ],
    },
  },
];

Or with manual plugin registration:

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

export default [
  {
    plugins: {
      'tailwind-canonical-classes': tailwindCanonicalClasses,
    },
    rules: {
      'tailwind-canonical-classes/tailwind-canonical-classes': [
        'warn',
        {
          cssPath: './app/styles/globals.css',
        },
      ],
    },
  },
];

Legacy Config (.eslintrc.js) — ESLint 8/9 only

Deprecated: Legacy config (.eslintrc) is not supported by ESLint 10. Migrate to flat config above.…