Carles Andres' avatarHomeBlogReference
Back to reference

Configuring oxlint with eslint-plugin-tailwindcss

Updated on 7/26/2026
This is a reference article.
Reference articles are written with the help of AI agents, after we have managed to solve a problem.

TL;DR

  • Install eslint-plugin-tailwindcss for Tailwind v4, or eslint-plugin-tailwindcss@3 for Tailwind v3.
  • Add it to jsPlugins in .oxlintrc.json, then enable the Tailwind rules you want.
  • Run npx oxlint . (or npx oxlint --fix . for autofixable rules).

Tools like Prettier with prettier-plugin-tailwindcss handle class sorting, but they don't catch semantic issues like using arbitrary values when Tailwind equivalents exist, contradicting classes, or verbose class combinations.

oxlint can load ESLint plugins via its alpha jsPlugins field, letting you use eslint-plugin-tailwindcss without switching your entire linting setup to ESLint.

Installation

For Tailwind v4 projects, install the stable v4 plugin:

bash
npm install -D eslint-plugin-tailwindcss

For Tailwind v3 projects, install the v3 plugin explicitly:

bash
npm install -D eslint-plugin-tailwindcss@3

Configuration

For a Tailwind v4 project, add the plugin to your .oxlintrc.json:

json
{  "$schema": "./node_modules/oxlint/configuration_schema.json",  "jsPlugins": ["eslint-plugin-tailwindcss"],  "settings": {    "tailwindcss": {      "cssConfigPath": "./src/app/globals.css"    }  },  "rules": {    "tailwindcss/enforces-negative-arbitrary-values": "warn",    "tailwindcss/enforces-shorthand": "warn",    "tailwindcss/no-contradicting-classname": "warn",    "tailwindcss/no-unnecessary-arbitrary-value": "warn"  }}

Recommended Rules

RuleWhat it doesExample
enforces-negative-arbitrary-valuesNormalizes negative arbitrary values syntax-top-[5px] → top-[-5px]
enforces-shorthandCombines axis utilities into shorthandmx-5 my-5 → m-5
no-contradicting-classnameCatches conflicting classes targeting the same propertyFlags p-2 p-3 as a conflict
no-unnecessary-arbitrary-valueReplaces arbitrary values with Tailwind equivalentsw-[100%] → w-full

Rules to Avoid

RuleWhy to skip it
no-arbitrary-valueToo strict—arbitrary values are often intentional for custom typography (clamp()), design-specific values, or cases where Tailwind doesn't have an equivalent
classnames-orderAlready handled by prettier-plugin-tailwindcss; enabling it creates redundant warnings

Running the Linter

Run oxlint as usual:

bash
npx oxlint .

If the plugin cannot resolve your Tailwind configuration, check that cssConfigPath points to the main Tailwind v4 CSS file. Avoid suppressing stderr because it can hide configuration errors.

Some rules support autofix:

bash
npx oxlint --fix .

Limitations

  • The jsPlugins feature is marked as alpha in oxlint and remains under active development
  • The Tailwind v4 plugin requires a path to the main Tailwind CSS file through tailwindcss.cssConfigPath
  • Not all rules have autofix support