Carles Andres' avatarHomeBlogReference
Back to reference

Configuring oxlint with eslint-plugin-tailwindcss

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 (beta for Tailwind v4, stable for 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 experimental jsPlugins field, letting you use eslint-plugin-tailwindcss without switching your entire linting setup to ESLint.

Installation

For Tailwind v4 projects, use the beta version:

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

For Tailwind v3 projects, use the stable version:

bash
npm install -D eslint-plugin-tailwindcss

Configuration

Add the plugin to your .oxlintrc.json:

json
{  "$schema": "./node_modules/oxlint/configuration_schema.json",  "jsPlugins": ["eslint-plugin-tailwindcss"],  "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 .

The Tailwind v4 beta plugin outputs warnings to stderr about config resolution. Suppress them with:

bash
npx oxlint . 2>/dev/null

Some rules support autofix:

bash
npx oxlint --fix .

Limitations

  • The jsPlugins feature is marked as experimental in oxlint and is not supported in the language server
  • For Tailwind v4, the beta plugin shows "Cannot resolve default tailwindcss config path" warnings but still functions correctly
  • Not all rules have autofix support