npm / oxlint-tailwindcss
oxlint-tailwindcss
What changed in oxlint-tailwindcss 0.5 to 1, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
28 breaking1 security28 new APIs and options4 performance17 behavior and defaults6 tooling80 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initoxlint-tailwindcss 1141 changes
Breaking changes 27
The declared Node.js range is now ^20.19.0 || >=22.12.0, matching oxlint’s requirement; older Node 20 releases are not supported.
The release requires Node.js
^20.19.0 || >=22.12.0.The supported minimum is now Tailwind CSS v4.1.15; versions 4.1.0–4.1.14 receive a clear
designSystemUnavailableinstead of a raw engine error.Bounds consecutive per-entry-point worker failures: after three, failures become sticky and the run fails fast; success clears the budget and the sticky state expires after a backoff window.
Engines older than v4.1 and major-version mismatches fail as designSystemUnavailable; newer minor versions and minor build drift warn and lint best-effort.
The autofix wraps templates into the block convention, using source-line indentation and re-wrapping only over-budget lines while leaving conforming lines verbatim.
The rule measures the longest individual line instead of the raw multiline template length, so splitting a string across lines can satisfy printWidth.
The rule now reads selectors only when collecting classes declared in project CSS, so nine previously accepted false positives, including com, css, and 5rem, are reported as unknown.
Declaration-service failures now surface through no-conflicting-classes and no-unknown-classes instead of silently falling back to weaker behavior.
Reports one diagnostic per collapsible group instead of one per matching family; CI diagnostic counts may drop.
Recognizes 37 additional collapsible patterns, so patterns that were previously silent can now report.
With an entry point, checks shorthand merges against emitted declarations; without one, sizing merges only values that cannot come from a per-axis namespace.
Now reports the
(--x)shorthand spelling of arbitrary values, as well as the bracketed form.With an entry point configured, orders project-defined variants according to their actual selectors, moving generated-box variants innermost and treating combinators as reordering barriers.
Reports same-value class pairs as redundant, including numeric spellings that normalize to the same value; these findings can fail CI runs that previously passed.
The rule runs unconditionally without settings.tailwindcss.entryPoint; any entryPoint passed as a rule option is ignored.
Flags @container and @container-size together as conflicting container-type markers.
The rule now converts negative physical utilities, which may produce new reports for projects using them.
The rule now converts negative logical utilities, which may produce new reports for projects using them.
The no-op entryPoint option was dropped; configurations that set it should remove it.
Strict mode now sorts prefixed groups stably instead of collapsing them to the same priority.
Under a project prefix, correctly prefixed utilities are valid; unprefixed utilities are reported with a missingPrefix message and a quick-fix that adds the prefix. Component classes remain valid without a prefix.
Merges utilities with the same variant prefix, including stacked and arbitrary variants, while leaving different-variant and mixed-importance pairs untouched. Same-variant stacks now report and autofix.
DS-dependent rules now report one actionable designSystemUnavailable diagnostic per file for fatal design-system failures instead of silently skipping.
Filesystem auto-detection and the global last-loaded-path fallback are gone; configurations must declare entryPoint explicitly.
An explicit entryPoint is now required. Use a string for a single project or an array of { files, use } mappings for monorepos; the legacy string-array shape is removed.
Default worker timeouts increase to 60 seconds for initialization and 30 seconds per request, reducing failures on slow CI.
Security 1
The cache is namespaced per user, created with mode 0o700, and schema-validates reads; corrupt or poisoned files are removed and recomputed.
New APIs and options 24
When enabled, reports canonical forms that also set variables other utilities read, with an editor-applicable suggestion and no autofix; it is off by default.
The new jsx value wraps JSX attribute strings in place; the default never preserves the previous behavior, and JavaScript strings still only report.
The new sizing option converts widths and heights, including min/max forms and size utilities, when enabled; it is off by default.
Adds tailwindcss() for registering the plugin and its recommended rules through extends in oxlint.config.ts or a published shared config.
The new option reports canonical forms that mean something different in the project, naming both variants and providing no fix; it is off by default.
Adds
allowVariables: 'none' | 'runtime' | 'all'to allow pure CSS-variable references; the default remains'none', and runtime mode consults the design system.Adds an experimental, opt-in rule that reports native elements whose classes rebuild a configured component; it has no autofix.
Adds an opt-in rule that reports Tailwind default-palette colors in projects with their own theme colors, naming the project's colors as alternatives.
Adds an opt-in rule that reports runtime-built classes Tailwind will not generate; the recommended README config enables it as an error.
Accepts a per-rule
entryPoint; with a theme that defines its own colors, reports name those colors as replacements. Without an entry point or on stock Tailwind, the message is unchanged.Map a custom callee to a structured extractor such as tv, cva, classed, or flat so wrapped configuration receives deep extraction across all 24 rules.
Adds a group option for wrapLines: all, with newLine as the default; emptyLine separates variant runs with blank lines, and never skips grouping.
Adds opt-in width-based autofixing for template literals: overWidth wraps only lines exceeding printWidth, while all normalizes multiline or over-width templates.
Overrides the design-system disk-cache location so developers can pin it to a controlled path in CI or sandboxed builds.
Overrides sort, canonicalize, and declaration worker services' per-request timeout, allowing slow but functional machines or CI runners more time to complete requests.
Adds regex patterns matched against JSX attribute names, additive to the exact attributes list; invalid regex sources are skipped.
Set this to true to downgrade future-major and major-drift fatal errors to a warning and lint against an untested engine; engines older than v4.1 remain fatal.
Adds the float-left/float-start, clear-left/clear-start, and text-left/text-start pairs; verifies suggested classes exist when a design system is available.
Adds allow patterns to silence every pair involving a matching class or a specific two-class combination.
Adds reportRedundant: false to opt out of findings for class pairs that declare the same property with the same value.
Adds an allowlist option; it defaults to no-op behavior, so existing configurations keep working.
Adds a direction option; it defaults to no-op behavior, so existing configurations keep working.
Adds an allowlist option; it defaults to no-op behavior, so existing configurations keep working.
Adds a direction option; it defaults to no-op behavior, so existing configurations keep working.
Performance 3
After precomputing, the plugin removes its own cache files unused for 30 days; cache hits refresh file dates at most once a day, and other directory files are left alone.
Persists canonicalization results to disk across oxlint runs, reducing repeated worker round-trips for dynamic classes.
Keeps an LRU-bounded warm worker for each CSS entry point in monorepos, avoiding repeated design-system warmups when linting files from different packages.
Behavior and default changes 14
With the default direction of both, the rule now converts block-axis utilities using Tailwind 4.2 logical utilities; without an entry point, these are suggested but never autofixed.
The rule now converts block-axis utilities back to physical utilities and converts sizes when sizing is enabled; it does not touch display utilities.
String operands in
+concatenations are now linted; complete classes receive rules and fixes, while glued fragments stay unchanged and runtime classes can be reported byno-dynamic-classes.With an entry point and project-defined colors, the diagnostic now names the theme colors developers can use instead of a hardcoded value.
Typo suggestions use an edit allowance scaled to class length, reducing wrong quick-fixes on short classes while retaining close suggestions such as
flxetoflex.The first rule linting each file now reports unknown setting keys, wrong value types, invalid regular-expression patterns, and unknown callee extractor kinds once per file.
The autofixer no longer inserts whitespace that splits a class glued to a template interpolation; such cases are warn-only.
Becomes design-system optional; when entryPoint is configured, the all-mode newLine and emptyLine fixers consult it to strip the project prefix before grouping variants.
The plugin resolves the Tailwind engine per CSS entry point from the consumer's project, so monorepo packages can use their own pinned versions and avoid version-drift lint results.
Derives deprecated v3 renames from the design system and owns those diagnostics, including renames absent from the former hardcoded table.
Scans arbitrary values for color literals, including shorthands, inset utilities, and arbitrary properties; quoted strings and url() contents are excluded.
Compiles variant chains to detect invalid variants and off-scale values that produce no CSS; suggestions are checked against the design system.
Autofix rewrites v3 background and object-position spellings to their v4 axis-first form.
Tailwind v4 project prefixes are detected automatically from entryPoint and validated in the correct position, with no extra configuration.
Tooling 4
Adds a plugin that starts the project's
oxlint --lsplanguage server and checks edited files for errors before Claude finishes, sending Claude back once if errors are found.Adds an opt-in rule that reports hardcoded values numerically equal to named design-system tokens and suggests the token; it is report-only and has no autofix.
Now suggests full shorthands for axis pairs:
px-* py-*top-*andmx-* my-*tom-*.Rules that take options now declare meta.defaultOptions, allowing tooling such as IDEs and doc generators to read rule defaults without running the rule.
Fixes and other changes 68
The rule now finds a class wherever its selector puts it, allowing canonicalization reports and autofixes for variants such as in-*, *:, **:, and divide-* while still avoiding changes that alter the selector.
Relative components paths for no-borrowed-component-styles now resolve against each discovered oxlint config's directory.
Relative entryPoint values now resolve against each discovered oxlint config's directory, including JSONC and TypeScript configs.
Style declaration keys in style objects are skipped rather than read as Tailwind classes, preventing invalid-class reports for framework style objects.
When enabled with an engine lacking
canonicalizeCandidates, canonical and v3-rename maps stay empty while other rules continue working instead of failing the whole precompute.Uses one outermost-first variant ordering with or without an entry point; the ordering change can rewrite chains once when
--fixis run.Cache keys now include local
@pluginand@configfiles and imported or plugin-loaded package versions, avoiding stale class lists after edits or upgrades.Counts a template literal across its
${}parts as one class string and reports once; long templates can now exceed the configured maximum.Classes and custom properties from local stylesheets imported up to four levels deep are now recognized, including classes in
@layer components.Only dark-variant classes that set a color require a light-mode base; non-color filters, display, border width, and opacity are no longer reported for lacking one.
Named group and peer markers remain valid when a custom variant selector names
.groupor.peer; only component classes Tailwind does not generate are refused.Each file now uses its own config's rule options and settings, so
overridesand nested configs apply to the intended files without leaking across files.Insiders versions are treated as untested newer engines rather than rejected as too old, with a one-time notice before linting continues.
Rules and autofixes now leave text glued to
${}out of class checks and rewrites, preventing fixes from splitting runtime classes or moving fragments away from expressions.Autofixes arbitrary values under variants, such as dark:bg-white/[.08] to dark:bg-white/8, while retaining the value-preserving check.
Canonicalizes arbitrary variants such as data-[open]: and min-[40rem]: when the rewrite preserves the value; selector-changing rewrites remain unchanged.
No longer reports a plain CSS-variable shorthand swap, leaving that change to enforce-consistent-variable-syntax and preventing duplicate diagnostics and autofix oscillation.
The rule no longer flags a responsive class that restores a property overridden by an intermediate class, preventing regressions in responsive layouts.
No longer reports tooLong when a line's single class alone exceeds printWidth, avoiding an unactionable warning.
Malformed classes are resolved one at a time, so one bad class no longer masks a real typo in the same batch.
Malformed classes are resolved one at a time, so one bad class no longer masks a real typo in the same batch.
Request failures are no longer cached as sticky errors; the next keystroke re-spawns and retries the worker.
The rule checks the base token before rewriting classes with modifiers, preventing destructive autofixes when the color has no named token while preserving legitimate rewrites.
Skips composition fragments and only evaluates strings it can identify as the final class list on a native host element, avoiding false-positive reports.
Skips composition fragments and only evaluates strings it can identify as the final class list on a native host element, avoiding false-positive reports.
The cache key now includes the engine version per entry point, preventing packages with identical CSS but different engines from poisoning each other's cache entries.
The rule checks the class count on each line independently instead of counting classes across the whole multiline block.
The fixer preserves each surviving line's class grouping when collapsing a shorthand pair, transferring a line break forward when needed.
The fixer preserves each surviving line's class grouping when removing duplicates, transferring a line break forward when the class that opened a line is removed.
Whitespace-only lines before an indented closing backtick are preserved, while a genuine single-line trailing space is still stripped.
In strict mode, off-scale percentage classes now receive order information instead of being pushed to the front of the attribute.
Custom utilities with open value types are no longer reported when Tailwind accepts their classes, while values the type refuses still report.
Off-scale percentages accepted by Tailwind are no longer reported as typos; percentages unsupported by a prefix, such as p-4%, still report.
A prefix quick-fix is no longer offered when adding the prefix cannot make a class valid; the class reports as unknown with a spelling suggestion instead.
Named markers under a project prefix now report as needing the prefix rather than receiving a spelling suggestion that could delete the marker name.
The rule recognizes named group and peer markers as required classes, preventing false diagnostics and quick-fixes that drop marker names.
The rule now scans resolved CSS imports when checking whether a variable is defined, preventing token suggestions that could change the design.
Skips v3 renames handled by no-deprecated-classes, avoiding duplicate diagnostics; keep both rules enabled to report those renames.
Adds the shipped logical/physical pairs, verifies suggested classes exist when a design system is available, and converts inset-s-* and inset-e-* spellings.
With an entry point, matches base and dark variants by declared CSS property, reducing false positives for pairs that use different spellings.
Only reports canonicalizations that emit byte-identical CSS, preventing literal arbitrary values from being rewritten to variable-backed tokens that can resolve differently.
Determines conflicts from emitted CSS declarations and cascade order, avoiding composition false positives and recognizing conflicts in classes with user-written values or previously missing precomputed properties.
With an entry point configured, classifies project-defined variants by their actual selectors, avoiding incorrect redundancy reports for variants targeting generated boxes.
Recognizes Tailwind v4 typed CSS-variable shorthand classes instead of flagging them as unknown.
Only proposes or autofixes a token rewrite when the token resolves back to the variable written, or that variable is undefined, preventing design-changing rewrites.
Bundled into the published package instead of being a peer dependency, so installing oxlint-tailwindcss no longer requires installing @oxlint/plugins separately.
Relative string entryPoint values now resolve from the nearest enclosing .oxlintrc.json directory instead of the current working directory, so CLI and editor use the same package-local CSS.
Valid Tailwind v4 classes that getClassList() does not enumerate are no longer reported as typos.
Variants that change the selector target, including * and **, are now reordering barriers.
Prefix and variant order are now resolved per entry point, fixing monorepos with differing package settings.
Failed design-system loads are retried once per process instead of paying the initialization cost on every call.
The worker path now rounds rem/em/px floats so autofixes do not write imprecise values into source.
Autofixes now negate only plain numeric dimensions, avoiding invalid rewrites of calc() and var() values.
The rule no longer treats attribute order as determining CSS precedence or flags an exact duplicate as conflicting with itself.
The rule no longer reports idiomatic display or position pairs that set the same property under different names.
Invalid user regexes in patterns are skipped instead of crashing lint with a raw SyntaxError.
Suggestions now preserve the ! modifier and work behind variants.
Cache keys now include locally imported CSS so changes to an @import file do not serve a stale design system.
Stale precompute locks are reclaimed by exclusive rename to avoid a coordination race.
Synchronous worker failures now report their real cause instead of a misleading timeout.
Invalid user regexes are skipped instead of crashing lint with a raw SyntaxError.
Workers now propagate load-failure causes and guard against oversized responses.
The rule no longer reorders the project prefix out of first position, which could produce no CSS.
Precompute runs in a worker thread instead of forking the oxlint host, avoiding cold-cache ENOMEM failures on memory-constrained CI runners.
Design-system load failures are memoized, so repeated rule attempts no longer produce thousands of errors; failures are invalidated when the CSS changes.
Memory-related load errors now receive a memory-specific hint pointing to memory pressure, oxlint concurrency, or runner memory.
Class extraction now scans array values in tv(), cva(), and cn(), including nested arrays, strings, and ternaries, so rules no longer ignore those classes.
A content-hash-scoped file lock serializes cold-cache precomputation across parallel isolates, avoiding simultaneous Node forks that could exhaust memory.
oxlint-tailwindcss 0.87 changes
Behavior and default changes 2
Utilities from this plugin are recognized across all DS-dependent rules when the plugin is imported into the CSS entry point.
Utilities from this plugin are recognized across all DS-dependent rules when the plugin is imported into the CSS entry point.
Fixes and other changes 5
Same-prefix class pairs such as duration-300 and duration-500 now correctly report instead of silently passing.
Recognizes later classes that refine one property of a shorthand as composition, while preserving direction-sensitive conflicts.
Mask gradient combinations now compose correctly, while conflicts in the same gradient slot still report.
Stops flagging arbitrary color values that wrap CSS variables in color functions or fallbacks.
Handles multi-segment utilities so values such as bg-[var(--color-red-500)] autofix to bg-red-500.
oxlint-tailwindcss 0.75 changes
Breaking changes 1
The rule now checks legacy v3 class spellings that produce valid CSS in v4 and canonicalizes them instead of silently skipping them.
Fixes and other changes 4
Legacy v3 class spellings that produce valid CSS in v4 are added to the valid set, so this rule no longer flags them.
Autofix rules preserve whitespace separators when rebuilding multiline class strings, avoiding collapsing indentation into a single space.
When collapsing whitespace, the rule now preserves newlines and following indentation, preventing autofix oscillation with enforce-consistent-line-wrapping.
Fixes precompute child-process module resolution under pnpm strict hoisting by resolving the module from the plugin's install location.
oxlint-tailwindcss 0.66 changes
New APIs and options 1
Adds a setting, defaulting to 16, that controls px→named class conversion in enforce-canonical.
Performance 1
Linting is about 5x faster: named classes avoid a worker-thread round-trip, and remaining worker requests are deduplicated.
Behavior and default changes 1
enforce-canonical now dynamically canonicalizes arbitrary user classes using Tailwind's API, falling back to the precomputed cache if the worker is unavailable.
Fixes and other changes 3
Canonicalization now processes each class separately, preserving output order and length when inputs contain duplicate classes.
The plugin no longer emits this warning when running in multiple oxlint worker threads because the redundant exit listener was removed.
The rule now keeps pseudo-element variants innermost in both static and design system ordering modes, preventing broken CSS in Tailwind v4.
oxlint-tailwindcss 0.55 changes
New APIs and options 3
Set to oxlint-tailwindcss to see which design system is loaded for each file.
Set to true to log which design system is loaded for each file; logging is disabled by default.
Accepts an array of entry points; for each file, the plugin selects the entry point whose directory is closest in the filesystem tree, enabling monorepo configuration.
Tooling 2
Six rules now declare their default options in the rule schema, making defaults visible to tooling.
Ten rules now provide IDE quick-fixes for additional errors, including replacing unknown classes with a Levenshtein suggestion.