oxlint-tailwindcss: A Native Linting Solution for Tailwind CSS v4

oxlint-tailwindcss: el plugin de linting que Tailwind v4 necesitaba

Sergio Azócar developed oxlint-tailwindcss as a native plugin to address linting gaps in Tailwind CSS v4 projects. The tool implements 22 specialized rules using the @oxlint/plugins API to eliminate the overhead associated with JavaScript-based compatibility layers.

Why This Matters

Native linting plugins solve the performance bottleneck inherent in traditional ESLint wrappers by sharing the same parsing cycle as the core engine. This technical approach allows for real-time validation of complex CSS class extractions without the latency of translation layers or repeated design system loading. For engineering teams, this translates to faster CI/CD pipelines and immediate developer feedback during the authoring process. By utilizing a Rust-optimized toolchain, the plugin maintains the high-performance standards expected of the oxlint ecosystem while supporting modern Tailwind v4 features like canonical form mapping and logical property enforcement.

Key Insights

• Native integration with @oxlint/plugins (2026) avoids the performance overhead of jsPlugins or ESLint interoperability layers.
• The plugin features a zero-configuration engine that auto-detects Tailwind entry points such as app.css or globals.css containing @import ‘tailwindcss’.
• Robust class extraction supports complex patterns including cva(), tv() slots, ternary operators, and tagged templates (tw...).
• The no-conflicting-classes rule identifies specific property overlaps and warns developers which utility class will take precedence based on source order.
• Development utilized the VoidZero ecosystem, including tsdown for builds and oxfmt for formatting, ensuring a high-performance toolchain throughout the project.

Working Examples

Basic configuration for .oxlintrc.json to enable native Tailwind rules.

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

Examples of correctness rules detecting conflicting classes and improper dark mode usage.

// ❌ Conflict detection
<div className="text-red-500 text-blue-500" />
// "text-red-500" and "text-blue-500" affect "color".
// "text-blue-500" takes precedence.

// ❌ Missing light mode base
<div className="dark:bg-gray-900" />
// ✅ Corrected
<div className="bg-white dark:bg-gray-900" />

Practical Applications

• Design System Enforcement: Use no-hardcoded-colors to block arbitrary values like bg-[#ff5733], forcing developers to utilize the standardized color palette. Pitfall: Over-reliance on arbitrary values leads to a fragmented UI that is difficult to theme or maintain.
• Complexity Management: Implement max-class-count to flag elements exceeding 20 classes, serving as a technical signal to extract logic into smaller components. Pitfall: Ignoring class density results in unreadable JSX that complicates peer reviews and refactoring efforts.
• Accessibility and RTL Support: Deploy enforce-logical to automatically convert physical properties like ml-4 to logical variants like ms-4 via autofix. Pitfall: Using physical properties in projects requiring multi-directional support creates layout bugs in RTL locales.

References:

• https://dev.to/sergioazoc/oxlint-tailwindcss-el-plugin-de-linting-que-tailwind-v4-necesitaba-41j9