unstale

npm / tailwindcss

tailwindcss

What changed in tailwindcss 3 to 4, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-17.

7 breaking2 deprecations31 new APIs and options2 performance28 behavior and defaults11 tooling100 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@unstale/cli 0.1.0 on npm

tailwindcss 4180 changes

Breaking changes 7

  • Selectors combining an attribute selector and element selector without spacing are parsed as two selectors.

    4.3.3release notes

  • This syntax now generates font-size declarations instead of color declarations.

    4.3.2release notes

  • Requires --value(…) in functional @utility definitions.

    4.3.0release notes

  • Logical end utilities are canonicalized into corresponding inset-e-* utilities, including negative versions.

    4.2.3release notes

  • Logical start utilities are canonicalized into corresponding inset-s-* utilities, including negative versions.

    4.2.3release notes

  • Placeholder utilities now read their color from --placeholder-color.

    4.2.3release notes

  • The deprecated overflow-ellipsis utility is canonicalized into text-ellipsis.

    4.2.3release notes

Deprecations 2

  • The end-* utilities are deprecated in favor of inset-e-* utilities.

    4.2.0release notes

  • The start-* utilities are deprecated in favor of inset-s-* utilities.

    4.2.0release notes

New APIs and options 31

Performance 2

  • Scanning JSONL and NDJSON files is faster.

    4.2.3release notes

  • The Oxide scanner performs fewer file system walks in bigger projects.

    4.2.0release notes

Behavior and default changes 28

  • Bare spacing values now work with auto-cols utilities.

    4.3.2release notes

  • Bare spacing values now work with auto-rows utilities.

    4.3.2release notes

  • Can now be used with CSS mixins.

    4.3.1release notes

  • One-valued spacing utilities generate var(--spacing) instead of calc(var(--spacing) * 1).

    4.3.1release notes

  • Can now be used inside addBase.

    4.3.1release notes

  • Adds parentheses when whitespace removal would hurt readability.

    4.3.0release notes

  • Preserves the original unit in arbitrary values instead of converting to base units.

    4.3.0release notes

  • Canonicalizes arbitrary :has() variants to the has-[…] form.

    4.3.0release notes

  • Allows multiple utility definitions with the same name when their value types differ.

    4.3.0release notes

  • Allows @variant to use stacked variants such as hover:focus.

    4.3.0release notes

  • Allows @variant to use compound variants such as hover and focus.

    4.3.0release notes

  • Border side utility combinations are canonicalized into axis or all-side utilities.

    4.2.3release notes

  • .env and .env.* are now excluded from default content-file scanning.

    4.2.3release notes

  • The upgrade process no longer migrates files ignored by git.

    4.2.3release notes

  • Axis-specific overflow utilities are canonicalized into the combined overflow utility.

    4.2.3release notes

  • Axis-specific overscroll utilities are canonicalized into the combined overscroll utility.

    4.2.3release notes

  • Equivalent arbitrary padding utilities are canonicalized into shorthand utilities.

    4.2.3release notes

  • Scroll margin side combinations are canonicalized into axis or all-side utilities.

    4.2.3release notes

  • Scroll padding side combinations are canonicalized into axis or all-side utilities.

    4.2.3release notes

  • Canonicalization now prefers non-negative tracking utilities.

    4.2.3release notes

  • Canonicalizes calc(var(--spacing)*…) expressions into the --spacing(…) form.

    4.2.2release notes

  • Aspect-ratio fractions may now use multiples of .25, such as aspect-8.5/11.

    4.2.0release notes

  • The .jj directory is now ignored by default during content detection.

    4.2.0release notes

  • Utility names may now contain escape characters, improving formatter support.

    4.2.0release notes

  • Arbitrary utilities are now canonicalized to bare values when possible.

    4.1.18release notes

  • Candidate validation now behaves more like Oxide.

    4.1.18release notes

  • Canonicalization now combines text-* and leading-* classes.

    4.1.18release notes

  • Upgrade processing canonicalizes utilities containing 0 values.

    4.1.15release notes

Tooling 11

  • Named opacity modifiers now receive class suggestions from --opacity theme values.

    4.3.2release notes

  • Class candidates adjacent to Template Toolkit delimiters are now extracted from .tt, .tt2, and .tx files.

    4.3.2release notes

  • Class candidates are now extracted from Twig addClass calls.

    4.3.1release notes

  • Can be installed in Rspack projects without webpack as a peer dependency.

    4.3.1release notes

  • The v3-to-v4 migration now uses config.content.

    4.2.3release notes

  • Adds support for Vite 8 in the Tailwind CSS Vite integration.

    4.2.2release notes

  • The CLI emits a comment when source maps are saved to files.

    4.2.0release notes

  • A new package runs Tailwind CSS as a webpack plugin.

    4.2.0release notes

  • CSS parse errors now include the filename and line numbers, making failures easier to locate.

    4.1.18release notes

  • The environment API is now supported in the Vite integration.

    4.1.18release notes

  • The deprecated break-words utility is migrated to wrap-break-word during upgrades.

    4.1.15release notes

Fixes and other changes 99

  • Achromatic theme colors no longer shift hue when mixed in polar color spaces such as oklch.

    4.3.3release notes

  • Arbitrary hex colors now match theme colors case-insensitively during canonicalization.

    4.3.3release notes

  • CSS nesting is handled even when Lightning CSS is not run, including browser builds and Tailwind Play.

    4.3.3release notes

  • Fractional opacity modifiers now work with named shadow, text-shadow, drop-shadow, and inset-shadow sizes.

    4.3.3release notes

  • Preflight no longer overrides Firefox's native focus-visible outline styles for iframes.

    4.3.3release notes

  • The watcher dependency loads only for CLI watch mode, allowing one-off builds and polling when it cannot be loaded.

    4.3.3release notes

  • Explicit platform fonts replace generic system fonts so CJK text respects the page's lang attribute on Windows.

    4.3.3release notes

  • Earlier @source rules for nested files are scanned even when later rules reference parent folders.

    4.3.3release notes

  • --spacing(0) now optimizes to 0px, preserving its length type inside calc expressions.

    4.3.3release notes

  • PostCSS rebuilds when a preprocessor changes input CSS without changing the input file on disk.

    4.3.3release notes

  • The upgrade command no longer rewrites ignored files when run from a subdirectory.

    4.3.3release notes

  • Vite integration no longer triggers full page reloads for scanned files not yet loaded as modules.

    4.3.3release notes

  • JS plugins now resolve theme colors correctly when similarly prefixed color variables coexist.

    4.3.3release notes

  • Class candidates are now extracted from conditional Maud syntax.

    4.3.2release notes

  • Position try rules no longer trigger unknown at-rule warnings during CSS optimization.

    4.3.2release notes

  • Source patterns no longer scan unrelated sibling files and folders.

    4.3.2release notes

  • Watch mode no longer crashes on Windows when @source points to a missing directory.

    4.3.2release notes

  • Watch mode now rebuilds when the input CSS file changes in an ignored directory.

    4.3.2release notes

  • Prevents type errors when used with newer PostCSS patch releases.

    4.3.2release notes

  • Avoids HMR crashes when scanned files or directories are deleted.

    4.3.2release notes

  • Avoids crashes in Deno v2.8.x when context.parentURL is not a valid URL.

    4.3.2release notes

  • Variants used in addBase can now reference custom variants defined later.

    4.3.2release notes

  • Canonicalization avoids suggesting large spacing-scale values for arbitrary lengths.

    4.3.1release notes

  • Canonicalization no longer suggests invalid calc expressions.

    4.3.1release notes

  • Canonicalization no longer folds divisions when the result would require high precision.

    4.3.1release notes

  • Color utilities now work with custom shadow values containing calc expressions.

    4.3.1release notes

  • Upgrade no longer migrates empty class rules to invalid @utility rules.

    4.3.1release notes

  • Transitions between inset-shadow-none and other inset shadows now work correctly.

    4.3.1release notes

  • Removes deprecation warnings on Node 26 and newer.

    4.3.1release notes

  • Correctly negates @container queries, including style queries.

    4.3.1release notes

  • Canonicalization no longer crashes when plugin utilities throw for unsupported values.

    4.3.1release notes

  • Class candidates are now extracted from Twig removeClass calls.

    4.3.1release notes

  • No longer crashes when scanning files containing invalid UTF-8 bytes.

    4.3.1release notes

  • Source globs with symlinks are preserved.

    4.3.1release notes

  • Later source rules can re-include files excluded by earlier source-not rules.

    4.3.1release notes

  • Explicitly referenced source directories are scanned even when ignored by git.

    4.3.1release notes

  • Source globs ending in **/* preserve dynamic path segments and avoid scanning too many files.

    4.3.1release notes

  • Zero-valued spacing utilities generate 0 instead of calc(var(--spacing) * 0).

    4.3.1release notes

  • Standalone CLI binaries are ignored when scanning for class candidates.

    4.3.1release notes

  • Watch mode recovers when a tracked dependency is deleted and restored.

    4.3.1release notes

  • Serves ESM type declarations to ESM importers.

    4.3.1release notes

  • Fixes incorrect sourcemap warnings when using the Vite integration.

    4.3.1release notes

  • No longer crashes when scanning files containing invalid UTF-8 bytes.

    4.3.1release notes

  • Preserves significant underscore whitespace during canonicalization.

    4.3.0release notes

  • Prevents legacy end utilities without values from generating CSS.

    4.3.0release notes

  • Resolves relative @import paths from the correct directory with @tailwindcss/vite.

    4.3.0release notes

  • Prevents the upgrade process from migrating inline style attributes.

    4.3.0release notes

  • Preserves required whitespace around operators in negated arbitrary values.

    4.3.0release notes

  • Resolves package JavaScript entries instead of browser CSS entries with @tailwindcss/vite.

    4.3.0release notes

  • Resolves relative @plugin paths from the correct directory with @tailwindcss/vite.

    4.3.0release notes

  • Exports the missing PluginWithConfig type from tailwindcss/plugin for plugin config type inference.

    4.3.0release notes

  • Prevents legacy start utilities without values from generating CSS.

    4.3.0release notes

  • Resolves imports relative to base when result.opts.from is not provided.

    4.3.0release notes

  • Ensures CSS files containing @variant are processed by @tailwindcss/vite.

    4.3.0release notes

  • Imports in @import and @plugin now resolve correctly when using Vite aliases in @tailwindcss/vite.

    4.2.4release notes

  • Invalid characters exceeding the valid Unicode code point range no longer cause a crash.

    4.2.3release notes

  • Negative arbitrary values move the minus sign inside the arbitrary value.

    4.2.3release notes

  • Negative arbitrary margin values move the minus sign outside the arbitrary value.

    4.2.3release notes

  • Stopping the upgrade process no longer empties files while the process is running.

    4.2.3release notes

  • Imports with query parameters are now treated as unique resources.

    4.2.3release notes

  • Prevents crashes when candidates contain prototype properties such as row-constructor.

    4.2.2release notes

  • Prevents crashes when canonicalizing utilities containing @property at-rules.

    4.2.2release notes

  • Improves canonicalization for bare values exceeding default spacing scale suggestions.

    4.2.2release notes

  • Prevents canonicalization from returning an empty list instead of the expected utility.

    4.2.2release notes

  • Skips full reloads for server-only modules scanned by client CSS with @tailwindcss/vite.

    4.2.2release notes

  • Trailing dashes in functional utility names are allowed for backwards compatibility.

    4.2.1release notes

  • Classes containing periods within curly braces in MDX files are now detected correctly.

    4.2.1release notes

  • Astro v5 import aliases now work without crashing with the Vite integration.

    4.2.0release notes

  • Utility detection now handles names containing capital letters followed by numbers.

    4.2.0release notes

  • Prevents color-mix values from receiving a double @supports wrapper.

    4.2.0release notes

  • Class extraction now works correctly for Rails strict locals.

    4.2.0release notes

  • The @source inline() argument may now contain surrounding whitespace.

    4.2.0release notes

  • Changes to external files listed via @source now trigger a full page reload with the Vite integration.

    4.2.0release notes

  • Utility name validation now matches Oxide scanner rules.

    4.2.0release notes

  • Using @variant inside @custom-variant no longer causes an infinite loop.

    4.2.0release notes

  • Arbitrary property utilities with a top-level ! in the value are now skipped correctly.

    4.1.18release notes

  • The CLI now handles duplicate command-line arguments correctly.

    4.1.18release notes

  • Color-mix fallback rules are no longer emitted inside keyframes.

    4.1.18release notes

  • Backwards compatibility for the content theme key in JavaScript configs is improved.

    4.1.18release notes

  • The CLI no longer hangs when its output is /dev/stdout.

    4.1.18release notes

  • The upgrade process now handles future and experimental configuration keys.

    4.1.18release notes

  • JavaScript configs now handle special defaults such as ringColor.DEFAULT correctly.

    4.1.18release notes

  • Comments in Ruby files are skipped when checking for class names.

    4.1.18release notes

  • Validation of source(…) now happens relative to the file containing it.

    4.1.18release notes

  • Theme keys from JavaScript configs and plugins now preserve their original case.

    4.1.18release notes

  • The CLI now writes source maps correctly when running in watch mode.

    4.1.18release notes

  • Legacy JavaScript APIs now substitute @variant correctly.

    4.1.17release notes

  • Prevents an occasional crash on Windows when Tailwind CSS is loaded into a worker thread.

    4.1.17release notes

  • Canonicalization of arbitrary variants with attribute selectors is fixed.

    4.1.16release notes

  • Canonicalization is improved for & > :pseudo and & :pseudo arbitrary variants.

    4.1.16release notes

  • Candidates with an empty data type are discarded.

    4.1.16release notes

  • Invalid colors caused by nested & are fixed.

    4.1.16release notes

  • At-rules parse correctly when they contain a tab character.

    4.1.15release notes

  • Safari devtools rendering is fixed when Tailwind uses color-mix fallbacks.

    4.1.15release notes

  • Lightning CSS warnings for :deep, :slotted, and :global are suppressed.

    4.1.15release notes

  • Important utilities no longer affect other utilities.

    4.1.15release notes

  • Named groups now work with not-*, has-*, and in-* variants.

    4.1.15release notes

  • The theme(…) function no longer indexes into strings.

    4.1.15release notes

  • Theme keys are resolved correctly when one key name starts with another in JS configs and plugins.

    4.1.15release notes

tailwindcss 31 changes

Fixes and other changes 1

  • Fixed sibling-*() functions used inside calc(…) so they no longer break.

    3.4.19release notes