Native Linting for Tailwind CSS v4: Introducing oxlint-tailwindcss

oxlint-tailwindcss: the linting plugin Tailwind v4 needed

Developer Sergio Azócar built a native oxlint plugin to bridge the gap between Tailwind CSS v4 and the high-performance oxc ecosystem. The tool features 22 specialized linting rules that share the same parsing cycle as oxlint for zero-overhead performance.

Why This Matters

Traditional ESLint plugins for Tailwind CSS often suffer from performance overhead due to interoperability layers or lack full support for v4’s new architecture. By utilizing the @oxlint/plugins API directly, this tool eliminates translation layers, allowing for real-time linting that scales with large utility-first codebases without sacrificing the speed oxlint is known for.

Key Insights

• Native integration with the @oxlint/plugins API allows the plugin to share the same parsing cycle as oxlint, eliminating interoperability overhead.
• The Correctness category includes no-unknown-classes, which uses fuzzy matching to suggest fixes for typos like itms-center to items-center.
• Automatic entry point detection identifies Tailwind v4 configurations in app.css or globals.css containing @import tailwindcss without manual setup.
• The plugin supports complex class extraction from tools like cva(), tv(), and twMerge() across JSX attributes and template literals.
• The development toolchain utilizes the VoidZero ecosystem, including tsdown for builds and oxfmt for formatting, ensuring high-speed execution.

Working Examples

Configuration example for .oxlintrc.json

{"jsPlugins": ["oxlint-tailwindcss"],"rules": {"tailwindcss/no-unknown-classes": "error","tailwindcss/no-conflicting-classes": "error","tailwindcss/enforce-sort-order": "warn"}}

Example of no-conflicting-classes rule detection

<div className="text-red-500 text-blue-500" />
// "text-red-500" and "text-blue-500" affect "color".
// "text-blue-500" takes precedence (appears later).

Practical Applications

• Design system enforcement: Use no-hardcoded-colors to forbid arbitrary hex codes like bg-[#ff5733] that erode system consistency.
• Accessibility and Internationalization: Apply enforce-logical to automatically convert physical properties like ml-4 to logical ones like ms-4 for LTR/RTL support.
• Refactoring signals: Implement max-class-count to trigger warnings when elements exceed 20 classes, indicating it is time to extract a component.
• Code consistency: Use enforce-shorthand to automatically merge individual properties like mt-2 mr-2 mb-2 ml-2 into a single m-2 utility.

References:

• https://dev.to/sergioazoc/oxlint-tailwindcss-the-linting-plugin-tailwind-v4-needed-fm2