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 your JSX/TSX 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:

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

Or with yarn:

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

Or with pnpm:

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

$3

- Node.js >= 18.0.0
- ESLint >= 8.0.0
- Tailwind CSS v4
- @tailwindcss/node package

🚀 Quick Start

1. Install the plugin (see Installation)

2. Add to your ESLint config:

Flat Config (ESLint 9+) - eslint.config.mjs:
`javascript
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:
`javascript
module.exports = {
plugins: ['tailwind-canonical-classes'],
rules: {
'tailwind-canonical-classes/tailwind-canonical-classes': [
'warn',
{
cssPath: './app/styles/globals.css',
},
],
},
};
`

3. Run ESLint:
`bash
npx eslint . --fix
`

⚙️ Configuration

$3

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

export default [
{
plugins: {
'tailwind-canonical-classes': tailwindCanonicalClasses,
},
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']
},
],
},
},
];
`

$3

`javascript
module.exports = {
plugins: ['tailwind-canonical-classes'],
rules: {
'tailwind-canonical-classes/tailwind-canonical-classes': [
'warn',
{
cssPath: './app/styles/globals.css',
rootFontSize: 16,
calleeFunctions: ['cn', 'clsx'],
},
],
},
};
`

📖 Options

$3

- Type: string
- Description: Path to your Tailwind CSS file
- Supported formats:
- Relative path: Resolved relative to your project root (where ESLint config is located)
- Absolute path: Full filesystem path to your CSS file

Examples:
`javascript
cssPath: './app/styles/globals.css' // Relative to project root
cssPath: './src/index.css' // Another relative example
cssPath: '/absolute/path/to/styles.css' // Absolute path
`

$3

- Type: number
- Default: 16
- Description: Root font size in pixels for rem calculations. This should match your CSS root font size setting.

Example:
`javascript
rootFontSize: 16 // Default (16px = 1rem)
rootFontSize: 14 // If your root font size is 14px
`

$3

- Type: string[]
- Default: ['cn', 'clsx', 'classNames', 'twMerge', 'cva']
- Description: Array of utility function names to check for Tailwind classes. The plugin will detect and canonicalize classes passed as string arguments to these functions.

Example:
`javascript
calleeFunctions: ['cn', 'clsx'] // Only check cn() and clsx()
calleeFunctions: ['customFn'] // Check a custom utility function
`

💡 Usage Examples

$3

Before:
`tsx


After auto-fix:
`tsx


1. String literals:
`tsx


2. Template literals (static parts only):
`tsx