@poupe/eslint-plugin-tailwindcss

ESLint plugin for Tailwind CSS v4 with advanced linting rules.

Features

• 🎯 Tailwind CSS v4 Support - Full support for the latest Tailwind syntax
• 🔍 Smart Validation - Validates directives, modifiers, and utility classes
• 🚀 Auto-fixable Rules - Many rules can automatically fix issues
• 📦 Preset Configurations - Ready-to-use configs for different strictness levels
• 🎨 Theme-aware - Encourages consistent use of design tokens
• ⚡ Performance - Optimized for large codebases

Requirements

• ESLint 9.0 or higher
• Node.js 18.0 or higher
• Flat config format (eslint.config.js)

Installation

# pnpm
pnpm add -D @poupe/eslint-plugin-tailwindcss @eslint/css

# npm
npm install -D @poupe/eslint-plugin-tailwindcss @eslint/css

# yarn
yarn add -D @poupe/eslint-plugin-tailwindcss @eslint/css

Note: This plugin requires @eslint/css as a peer dependency for CSS parsing.

Usage

Basic Setup

Create an eslint.config.mjs file with TypeScript type checking:

// @ts-check
import tailwindcss from '@poupe/eslint-plugin-tailwindcss';

export default [
  {
    files: ['**/*.css'],
    language: 'css/css', // Required
    plugins: {
      tailwindcss,
    },
    rules: {
      'tailwindcss/valid-theme-function': 'error',
      'tailwindcss/valid-modifier-syntax': 'error',
      'tailwindcss/valid-apply-directive': 'error',
      'tailwindcss/no-arbitrary-value-overuse': 'warn',
      'tailwindcss/prefer-theme-tokens': 'warn',
      'tailwindcss/no-conflicting-utilities': 'error',
    },
  },
];

Using Preset Configurations

Use preset configurations for a quick start:

// @ts-check
import tailwindcss from '@poupe/eslint-plugin-tailwindcss';

export default [
  {
    files: ['**/*.css'],
    language: 'css/css',
    plugins: {
      tailwindcss,
    },
    rules: {
      // Use recommended settings
      ...tailwindcss.configs.recommended.rules,

      // Override specific rules if needed
      'tailwindcss/no-arbitrary-value-overuse': 'error',
    },
  },
];

Available Configurations

minimal

Basic syntax validation only. Good for existing projects.

• ✅ valid-theme-function
• ✅ valid-modifier-syntax
• ✅ valid-apply-directive
• ✅ no-invalid-at-rules
• ✅ no-invalid-properties
• ✅ no-duplicate-imports
• ✅ no-empty-blocks
• ✅ no-important

recommended (Default)

Balanced set of rules for most projects.

• ✅ All rules from minimal
• ✅ no-conflicting-utilities
• ⚠️ no-arbitrary-value-overuse (warning)
• ⚠️ prefer-theme-tokens (warning)

strict

All rules enabled with strict settings. Best for new projects.

• ✅ All rules as errors
• ✅ Strictest configuration options
• ✅ Includes optional @eslint/css rules (logical properties, relative units, layers)

Complete Example

Here's a comprehensive eslint.config.mjs with TypeScript support:

// @ts-check
import js from '@eslint/js';
import typescript from '@typescript-eslint/eslint-plugin';
import tsParser from '@typescript-eslint/parser';
import css from '@eslint/css';
import tailwindcss from '@poupe/eslint-plugin-tailwindcss';

export default [
  // JavaScript/TypeScript files
  {
    files: ['**/*.{js,mjs,cjs,ts,tsx}'],
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        ecmaVersion: 'latest',
        sourceType: 'module',
      },
    },
    plugins: {
      '@typescript-eslint': typescript,
    },
    rules: {
      ...js.configs.recommended.rules,
      ...typescript.configs.recommended.rules,
    },
  },

  // CSS files with Tailwind CSS support
  {
    files: ['**/*.css'],
    language: 'css/css',
    plugins: {
      css,
      tailwindcss,
    },
    rules: {
      // @eslint/css rules
      'css/no-duplicate-imports': 'error',
      'css/no-empty-blocks': 'error',

      // Tailwind CSS specific rules
      ...tailwindcss.configs.recommended.rules,
    },
  },
];

Rules

Possible Errors (Implemented)

Rules that catch potential bugs or invalid syntax.

Rule	Description	🔧
no-conflicting-utilities	Detects conflicting Tailwind utilities that affect the same CSS properties
no-duplicate-imports	Disallow duplicate @import rules
no-empty-blocks	Disallow empty rule blocks and at-rule blocks
no-invalid-at-rules	Disallow invalid at-rule names and syntax
no-invalid-named-grid-areas	Disallow invalid named grid areas in CSS Grid templates
no-invalid-properties	Disallow invalid CSS property names
use-baseline	Enforce use of widely-supported CSS features
valid-apply-directive	Validates the @apply directive usage
valid-modifier-syntax	Ensures Tailwind modifiers follow correct syntax patterns
valid-theme-function	Validates usage of the theme() function in CSS files	🔧

Best Practices (Implemented)

Rules that guide towards better code patterns and maintainability.

Rule	Description	🔧
no-arbitrary-value-overuse	Warns when too many arbitrary values are used instead of theme tokens
no-important	Discourage use of !important
prefer-logical-properties	Enforce the use of logical properties over physical properties	🔧
prefer-theme-tokens	Suggests using theme tokens instead of hard-coded values
relative-font-units	Prefer relative units (rem/em) over absolute (px) for fonts
use-layers	Encourage use of @layer for better CSS architecture

Stylistic Issues (Implemented)

Rules that enforce code style and formatting conventions.

Rule	Description	🔧
consistent-spacing	Enforces consistent spacing around colons in CSS declarations	🔧

🔧 = Automatically fixable

Unimplemented Rules (Roadmap)

Possible Errors (Planned)

Core CSS Validation (Additional)

Rules that catch general CSS syntax errors and invalid constructs.

Rule	Description	🔧	Status
no-unknown-pseudo-class	Detect invalid pseudo-classes		Planned
no-unknown-pseudo-element	Detect invalid pseudo-elements		Planned

Best Practices (Planned)

CSS Best Practices (@eslint/css parity)

Rules that enforce modern CSS patterns.

Rule	Description	🔧	Status

Tailwind v4 Compatibility

Rules specific to Tailwind CSS version management and migration.

Rule	Description	🔧	Status
version-compatibility	Enforce compatibility with specific Tailwind CSS versions		Planned
deprecated-features	Warn about deprecated Tailwind features		Planned
migrate-imports	Convert Tailwind v3 imports to v4 syntax	🔧	Priority
migrate-directives	Update deprecated Tailwind directives	🔧	Priority
migrate-config-to-css	Guide migration from JS config to CSS @theme		Planned
migrate-arbitrary-values	Update arbitrary value syntax between versions	🔧	Planned

Code Quality

Rules that enforce documentation and maintainability.

Rule	Description	🔧	Status
comment-word-disallowed-list	Disallow specified words in comments		Considering
require-description-comments	Require explanatory comments for complex selectors		Considering
tailwind-comment-directives	Validate Tailwind-specific comment directives	🔧	Considering

Stylistic Issues (Planned)

CSS Formatting (@eslint/css parity)

General CSS formatting rules.

Rule	Description	🔧	Status
indent	Enforce consistent indentation	🔧	Planned
brace-style	Enforce consistent brace placement	🔧	Planned
block-spacing	Enforce consistent spacing inside blocks	🔧	Planned
declaration-block-newline	Enforce line breaks within declaration blocks	🔧	Planned
rule-empty-line-before	Require or disallow empty lines before rules	🔧	Planned
property-sort-order	Enforce consistent property declaration order	🔧	Planned
at-rule-formatting	Format at-rules consistently	🔧	Planned
no-unnecessary-whitespace	Disallow unnecessary whitespace	🔧	Planned
property-formatting	Format property declarations consistently	🔧	Planned
selector-formatting	Format selectors consistently	🔧	Planned
value-formatting	Format property values consistently	🔧	Planned
media-query-formatting	Format media queries consistently	🔧	Planned

Tailwind-Specific Formatting

Rules for Tailwind CSS v4 specific constructs.

Rule	Description	🔧	Status
at-apply-formatting	Format @apply directives consistently	🔧	Planned
theme-formatting	Format @theme blocks consistently	🔧	Planned
enforce-class-order	Enforce consistent Tailwind utility class ordering	🔧	Priority

Comment Formatting

Rules for consistent comment styles.

Rule	Description	🔧	Status
comment-formatting	Format comments consistently	🔧	Considering
comment-style	Enforce consistent comment syntax	🔧	Considering
comment-empty-line-before	Require or disallow empty lines before comments	🔧	Considering
comment-capitalization	Enforce consistent comment capitalization	🔧	Considering
comment-length	Enforce maximum comment line length	🔧	Considering

Status Legend:

• Priority: High priority, will be implemented next
• Planned: Scheduled for implementation
• Considering: Under consideration, may be implemented

Advanced Features

Custom Syntax Support

This plugin extends @eslint/css with Tailwind CSS v4 syntax support:

• ✅ Directives: @theme, @import, @plugin, @utility, @variant, @source
• ✅ Functions: theme(), screen()
• ✅ Arbitrary Values: [value] syntax
• ✅ Modifiers: hover:, focus:, sm:, lg:, inert:, target:, open:, starting:, popover-open:, not-*:, in-*:, [&:state]:
• ✅ Stacked Variants: dark:hover:text-white
• ✅ Custom Variants: Created with @custom-variant

TypeScript Support

Full TypeScript support with exported types:

import type { TailwindCSSRules, TailwindCSSConfigs } from '@poupe/eslint-plugin-tailwindcss';

Configuration Examples

With TypeScript

// eslint.config.mjs
import tailwindcss from '@poupe/eslint-plugin-tailwindcss';
import typescript from '@typescript-eslint/eslint-plugin';
import tsParser from '@typescript-eslint/parser';

export default [
  // TypeScript configuration
  {
    files: ['**/*.{ts,tsx}'],
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        project: './tsconfig.json',
        tsconfigRootDir: import.meta.dirname,
      },
    },
    plugins: {
      '@typescript-eslint': typescript,
    },
    rules: {
      ...typescript.configs['recommended-type-checked'].rules,
    },
  },
  // Tailwind CSS configuration
  {
    files: ['**/*.css'],
    ...tailwindcss.configs.recommended,
  },
];

Vue.js Project

// eslint.config.mjs
import tailwindcss from '@poupe/eslint-plugin-tailwindcss';
import vue from 'eslint-plugin-vue';

export default [
  ...vue.configs['flat/recommended'],
  {
    files: ['**/*.{css,vue}'],
    ...tailwindcss.configs.recommended,
  },
];

With PostCSS

// @ts-check
// eslint.config.mjs
import tailwindcss from '@poupe/eslint-plugin-tailwindcss';

export default [
  {
    files: ['**/*.{css,pcss,postcss}'],
    ...tailwindcss.configs.strict,
  },
];

Troubleshooting

ESLint can't find the plugin

Make sure you're using ESLint flat config format (ESLint 9+):

// @ts-check
// ✅ Correct - eslint.config.mjs (ESM format)
export default [
  tailwindcss.configs.recommended,
];

// ❌ Wrong - .eslintrc.js (legacy format)
module.exports = {
  extends: ['@poupe/eslint-plugin-tailwindcss'],
};

Rules not applying to CSS files

Ensure your config targets CSS files:

export default [
  {
    files: ['**/*.css'], // Don't forget this!
    ...tailwindcss.configs.recommended,
  },
];

Contributing

Contributions are welcome! Please read our contributing guidelines first.

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

# Build
pnpm build

# Lint and auto-fix
pnpm lint

# Type checking
pnpm type-check

# Run all pre-commit checks
pnpm precommit

Testing

Tests are written using Vitest and ESLint's RuleTester. Each rule should have comprehensive test coverage including:

• Valid code examples
• Invalid code examples with expected errors
• Auto-fix scenarios (where applicable)
• Edge cases and CSS parsing quirks

Example test structure:

import { RuleTester } from 'eslint';
import css from '@eslint/css';
import { ruleName } from '../../rules/rule-name';

const ruleTester = new RuleTester({
  language: 'css/css',
  plugins: { css },
});

describe('rule-name', () => {
  ruleTester.run('tailwindcss/rule-name', ruleName, {
    valid: [
      // Valid test cases
    ],
    invalid: [
      // Invalid test cases with expected errors
    ],
  });
});

License

MIT © Apptly Software Ltd