@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

1# pnpm
2pnpm add -D @poupe/eslint-plugin-tailwindcss @eslint/css
3
4# npm
5npm install -D @poupe/eslint-plugin-tailwindcss @eslint/css
6
7# yarn
8yarn 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:

1// @ts-check
2import tailwindcss from '@poupe/eslint-plugin-tailwindcss';
3
4export default [
5  {
6    files: ['**/*.css'],
7    language: 'css/css', // Required
8    plugins: {
9      tailwindcss,
10    },
11    rules: {
12      'tailwindcss/valid-theme-function': 'error',
13      'tailwindcss/valid-modifier-syntax': 'error',
14      'tailwindcss/valid-apply-directive': 'error',
15      'tailwindcss/no-arbitrary-value-overuse': 'warn',
16      'tailwindcss/prefer-theme-tokens': 'warn',
17      'tailwindcss/no-conflicting-utilities': 'error',
18    },
19  },
20];

Using Preset Configurations

Use preset configurations for a quick start:

1// @ts-check
2import tailwindcss from '@poupe/eslint-plugin-tailwindcss';
3
4export default [  {    files: ['**/*.css'],
5    language: 'css/css',
6    plugins: {
7      tailwindcss,
8    },
9    rules: {
10      // Use recommended settings
11      ...tailwindcss.configs.recommended.rules,
12
13      // Override specific rules if needed
14      'tailwindcss/no-arbitrary-value-overuse': 'error',
15    },
16  },
17];

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:

1// @ts-check
2import js from '@eslint/js';
3import typescript from '@typescript-eslint/eslint-plugin';
4import tsParser from '@typescript-eslint/parser';
5import css from '@eslint/css';
6import tailwindcss from '@poupe/eslint-plugin-tailwindcss';
7
8export default [
9  // JavaScript/TypeScript files
10  {
11    files: ['**/*.{js,mjs,cjs,ts,tsx}'],
12    languageOptions: {
13      parser: tsParser,
14      parserOptions: {
15        ecmaVersion: 'latest',
16        sourceType: 'module',
17      },
18    },
19    plugins: {
20      '@typescript-eslint': typescript,
21    },
22    rules: {
23      ...js.configs.recommended.rules,
24      ...typescript.configs.recommended.rules,
25    },
26  },
27
28  // CSS files with Tailwind CSS support
29  {
30    files: ['**/*.css'],
31    language: 'css/css',
32    plugins: {
33      css,
34      tailwindcss,
35    },
36    rules: {
37      // @eslint/css rules
38      'css/no-duplicate-imports': 'error',
39      'css/no-empty-blocks': 'error',
40
41      // Tailwind CSS specific rules
42      ...tailwindcss.configs.recommended.rules,
43    },
44  },
45];

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:

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

Configuration Examples

With TypeScript

1// eslint.config.mjs
2import tailwindcss from '@poupe/eslint-plugin-tailwindcss';
3import typescript from '@typescript-eslint/eslint-plugin';
4import tsParser from '@typescript-eslint/parser';
5
6export default [  // TypeScript configuration  {    files: ['**/*.{ts,tsx}'],
7    languageOptions: {
8      parser: tsParser,
9      parserOptions: {
10        project: './tsconfig.json',
11        tsconfigRootDir: import.meta.dirname,
12      },
13    },
14    plugins: {
15      '@typescript-eslint': typescript,
16    },
17    rules: {
18      ...typescript.configs['recommended-type-checked'].rules,
19    },
20  },
21  // Tailwind CSS configuration
22  {
23    files: ['**/*.css'],
24    ...tailwindcss.configs.recommended,
25  },
26];

Vue.js Project

1// eslint.config.mjs
2import tailwindcss from '@poupe/eslint-plugin-tailwindcss';
3import vue from 'eslint-plugin-vue';
4
5export default [
6  ...vue.configs['flat/recommended'],
7  {
8    files: ['**/*.{css,vue}'],
9    ...tailwindcss.configs.recommended,
10  },
11];

With PostCSS

1// @ts-check
2// eslint.config.mjs
3import tailwindcss from '@poupe/eslint-plugin-tailwindcss';
4
5export default [
6  {
7    files: ['**/*.{css,pcss,postcss}'],
8    ...tailwindcss.configs.strict,
9  },
10];

Troubleshooting

ESLint can't find the plugin

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

1// @ts-check
2// ✅ Correct - eslint.config.mjs (ESM format)
3export default [
4  tailwindcss.configs.recommended,
5];
6
7// ❌ Wrong - .eslintrc.js (legacy format)
8module.exports = {
9  extends: ['@poupe/eslint-plugin-tailwindcss'],
10};

Rules not applying to CSS files

Ensure your config targets CSS files:

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

Contributing

Contributions are welcome! Please read our contributing guidelines first.

Development

1# Install dependencies
2pnpm install
3
4# Run tests
5pnpm test
6
7# Run tests in watch mode
8pnpm test:watch
9
10# Run tests with coverage
11pnpm test:coverage
12
13# Build
14pnpm build
15
16# Lint and auto-fix
17pnpm lint
18
19# Type checking
20pnpm type-check
21
22# Run all pre-commit checks
23pnpm 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:

1import { RuleTester } from 'eslint';
2import css from '@eslint/css';
3import { ruleName } from '../../rules/rule-name';
4
5const ruleTester = new RuleTester({
6  language: 'css/css',
7  plugins: { css },
8});
9
10describe('rule-name', () => {
11  ruleTester.run('tailwindcss/rule-name', ruleName, {
12    valid: [
13      // Valid test cases
14    ],
15    invalid: [
16      // Invalid test cases with expected errors
17    ],
18  });
19});

License

MIT © Apptly Software Ltd