eslint-plugin-tailwindcss

To use the plugin, import it into your eslint.config.js (or .mjs) file. You can extend the recommended configuration preset and must provide the cssConfigPath in the settings.tailwindcss object.

Note: cssConfigPath can be an absolute or relative path. If relative, the plugin will attempt to convert it to an absolute path.

// 1. import the plugin
import eslintPluginTailwindcss from "eslint-plugin-tailwindcss";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    // 2. Optional: extend an existing config preset
    extends: [eslintPluginTailwindcss.configs.recommended],
    settings: {
      // 3. Define the tailwindcss settings with the MANDATORY cssConfigPath
      tailwindcss: {
        cssConfigPath: "./src/styles/tailwind.css",
      },
    },
    // 4. Optional: customize the rules to your needs
    rules: {
      "tailwindcss/classnames-order": "warn",
      "tailwindcss/no-arbitrary-value": "warn",
      "tailwindcss/no-custom-classname": [
        "warn",
        { whitelist: ["custom\\-\"] },
      ],
      "tailwindcss/no-contradicting-classname": "warn",
    },
  },
]);

The no-unnecessary-arbitrary-value rule warns when you use arbitrary values (e.g., inset-[1px]) that could be replaced by a standard Tailwind CSS preset (e.g., inset-px).

This rule is included in the recommended configuration and is automatically fixable using the ESLint --fix flag or via editor suggestions.

Key Improvements in v4.1.0+

As of version v4.1.0, the rule is smarter and can resolve:

• Native presets: Replaces inset-[1px] with inset-px.
• Unitless values: Replaces z-[123] with z-123.
• Spacing-based values: Replaces m-[8px] with m-2 (based on your spacing configuration).

CSS Specificity and Cascading Order

All these class types (native presets, user presets, arbitrary values, and unitless values) have the same CSS specificity score of 10. Therefore, the order of declaration in your HTML determines which style wins. The cascading order from strongest to weakest is:

1. Native preset (e.g., inset-px)
2. User preset (e.g., inset-preset)
3. Arbitrary value (e.g., inset-[20px])
4. Generic <number> (e.g., inset-10)

Benefits

• Eliminates redundant classes.
• Improves searchability and refactoring.
• Ensures adherence to your Design System.
• Reduces the amount of generated CSS.

In v4, most settings must be defined within the shared settings rather than per-rule.

Key Configuration Changes

The cssConfigPath setting

The most critical setting is cssConfigPath, which must point to the main CSS file used by Tailwind CSS.

• If the path is absolute, it is used as is.
• If the path is relative, the plugin will attempt to convert it into an absolute path.

Renamed and Modified Settings

When migrating your configuration, note the following changes to setting names and behaviors:

Most rules use shared settings defined under settings.tailwindcss. These settings control how the plugin identifies Tailwind classes and which functions it parses.

Note for Tailwind CSS v4 users: The cssConfigPath must point to a .css file, not a .js file.

{
  settings: {
    tailwindcss: {
      // Attributes/props that could contain Tailwind CSS classes...
      // Optional, default values: ["class", "className", "ngClass", "@apply"]
      attributes: ["class"],
      // The (absolute or relative) path pointing to you main Tailwind CSS v4 config file.
      // It must be a `.css` file (v4), not a `.js` file (v3)
      // REQUIRED, as the default value may not work out-of-the-box
      cssConfigPath: "./styles/tailwind.css",
      // Functions/tagFunctions that will be parsed by the plugin.
      // Optional, default values: ["classnames", "classNames", "clsx", "cn", "ctl", "cva", "tv", "tw", "twMerge", "twJoin"]
      functions: ["twClasses"],
      // Used for "clsx", etc. to check keys instead of values
      // Optional, default values: ["classnames", "classNames", "clsx"]
      parseKeyFunctions: ["clsx"],
      // Keys to be ignored in object expressions
      // Optional, default values: ["defaultVariants", "compoundVariants", "compoundSlots"]
      ignoredKeys: ["defaultVariants", "compoundVariants", "compoundSlots", "specificKey"],
      // Max size of the Set or Map objects used for caching
      // Optional, default value: 250_000
      cacheMaxSize: 150_000,
      // Max lifetime of the cache set in ms
      // Optional, default value: 10 * 60 * 1000 (10 minutes)
      cacheMaxAge: 60 * 1000,
    },
  }
}