eslint-plugin-tailwind-canonical

An ESLint plugin that enforces canonical Tailwind CSS class names using Tailwind CSS v4's API.

中文文档 | Changelog | Contributing

Features

• 🔧 Auto-fix: Detects and automatically fixes non-canonical Tailwind arbitrary values classes
• ⚡ Fast: Uses Tailwind CSS v4's canonicalizeCandidates API
• 🎯 Comprehensive: Supports all arbitrary values formats (bracket and unit)
• 🔍 Multi-scenario: Works with JSX className and utility functions

Installation

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

Requirements

• Node.js >= 18.0.0
• ESLint >= 8.0.0
• Tailwind CSS v4

Configuration

ESLint 9+ (Flat Config)

import tailwindCanonical from 'eslint-plugin-tailwind-canonical';

export default [
    {
        plugins: {
            'tailwind-canonical': tailwindCanonical,
        },
        rules: {
            'tailwind-canonical/tailwind-canonical-classes': [
                'error',
                {
                    cssPath: './app/global.css', // Path to your Tailwind CSS file
                },
            ],
        },
    },
];

ESLint 8 (Legacy Config)

module.exports = {
    plugins: ['tailwind-canonical'],
    rules: {
        'tailwind-canonical/tailwind-canonical-classes': [
            'error',
            {
                cssPath: './app/global.css',
            },
        ],
    },
};

Options

cssPath (required)

Type: string

Path to your Tailwind CSS entry file. Can be relative or absolute.

Examples

JSX className

// ❌ Before
<div className="p-[1rem] m-[0.5rem] aspect-[476/226]">
    Content
</div>

// ✅ After auto-fix
<div className="p-4 m-2 aspect-476/226">
    Content
</div>

Utility Functions

// ❌ Before
cn('p-[1.5rem] m-[1rem]', 'bg-[green]')

// ✅ After auto-fix
cn('p-6 m-4', 'bg-green-500')

Responsive Prefixes

// ❌ Before
<div className="md:aspect-[1/2] lg:p-[2rem]">
    Content
</div>

// ✅ After auto-fix
<div className="md:aspect-1/2 lg:p-8">
    Content
</div>

How It Works

Uses Tailwind CSS v4's canonicalizeCandidates API to convert arbitrary values to canonical class names.

Contributing

Issues and Pull Requests are welcome!

Related Projects

• Tailwind CSS - A utility-first CSS framework
• ESLint - Find and fix problems in your JavaScript code

Support

If you find this project helpful, please give it a ⭐️ on GitHub!

License

MIT License