Nativewind 5.0 → latest: release plan & checklist

[danstepanov]

Hey y'all,

We're getting ready to promote Nativewind 5.0 from preview to latest. The goal is a minimal, stable upgrade from v4; no big surprises, just the must-have features and the bug fixes that genuinely block a clean release.

This post tracks what's left, who's on it, and a rough timeline. Feedback and help are very welcome (see the bottom).

Scope for 5.0

In scope:

A small set of must-have features

• new filter support, mix-blend-mode, and core bug fixes.
• Blocker-level bugs only.

Out of scope (deferred so they don't hold up the release)

• General enhancements and chores.
• Sandcastle app work.
• PR/release automation tooling.

If something isn't a blocker for a stable v5, it waits.

TODO

PR & issue triage (Mark & Dan)

• Audit and label all open PRs and issues to make clear what is required for 5.0 vs deferred.
• Review the outstanding RN SVG support and blend-mode PRs for inclusion.
• Merge the PRs that are ready across nativewind and react-native-css.

Timeline: kicking off this week, with reviews/merges happening over the next several days.
Migration guide (v4 → v5)

• Dan to update the v4 → v5 migration guide and changelog to make sure everything is clear.
• Dan to provide an LLM-assisted upgrade prompt/skill so most of the migration can be automated.

Timeline: in parallel with triage, ready before the final release.
Release candidate

• Cut an RC once the required PRs are merged.
• Let the RC bake ~2 weeks before promoting to latest.

A couple of notes on the RC:

"RC" means no more API-breaking changes, only bug fixes land between the RC and the final version.
Heads up on a known caveat: installs pinned to one RC version don't automatically pull later RCs, so please reinstall/update explicitly when testing newer RCs.
Promote to latest

• After the bake period with no outstanding blockers, move 5.0 to latest.

Rough timeline

1. Now → end of this week: PR/issue audit + labelling, merge ready PRs, migration guide drafted.
2. Then: Cut the RC.
3. ~2 weeks of RC bake: collect feedback, land bug fixes only.
4. After bake, blockers clear: promote 5.0 to latest (just a tagged release).

Dates are intentionally a bit loose with the bake window being the main fixed point.

Cadence

• Mark and Dan are syncing during weekly calls and in daily comms to track progress and address blockers early.
• Status will be posted here and in Discord as things move forward.

How you can help

• Try the current preview release and report any regressions from v4.
• Weigh in on the labelled PRs/issues if you have context or a use case.
• Once the RC is out, test it against your project using the prompt/skill that we'll release for migrating from v4 to v5. Flag anything that breaks, that's the whole point of the bake window.

Thanks ❤️

[danstepanov]

A bunch of PRs have been addressed and everything has been labeled appropriately (v5 vs deferred post 5.0)

• closed superfluous PRs
• merged a number of react-native-css PRs pertaining to v5 stability

Reviewing all the remaining issues labeled v5 stability this week.

Nishan (Expo) is reviewing my updates to the Expo skill for using Tailwind v4 with Expo.

[douglowder]

@danstepanov see my comment in your Expo PR -- we are going to rework the Expo skill so that it is a reference to your skills that you maintain.

[danstepanov]

For Dan

nativewind

• Issues (2 remaining)
• PRs (1 remaining)

react-native-css

• Issues (2 remaining)

For Mark

nativewind

• Issues (3 remaining)
• PRs (1 remaining)

react-native-css

• Issues (1 remaining)
• PRs (1 remaining)

Blocked (by above)

• Explore Nativewind knowledge MCP (have someone looking into this)
• Update the v4 → v5 migration guide and change log to make sure everything is clear.
• Provide an LLM-assisted upgrade prompt/skill so most of the migration can be automated.
• Cut an RC.

[XChikuX]

Please add an AI migration SKILL.md to the list of TODO's

[danstepanov]

Already there, second item under Migration guide (v4 → v5)

[XChikuX]

Please add from v2 -> v5 if possible.

[YevheniiKotyrlo]

Hi Dan, Mark — hope the 5.0 push is going well.

I've opened quite a few PRs here over the last month, and I realise that arriving all at once looks like a firehose. It's a backlog rather than a sprint: I've been using the library in production for a long time, patching things locally as I hit them so I could keep shipping, and writing each one up as I went. Submitting them was the last step, which is why they landed so close together. Genuinely no expectation that they're dealt with quickly.

The main thing worth saying: 26 of the 29 are bug fixes — only #388, #416 and #430 are features. Reading the 5.0 scope, core bug fixes are in scope, so more of these may be closer to the bar than the number of them suggests. Happy to label them myself against that bar if it's useful, or to mark whatever you'd rather defer.

Three are hard failures rather than wrong output:

• #390 — the babel import plugin quietly does nothing on Windows. path.resolve returns backslashes, so the forward-slash .split() never matches and relative React Native imports go unrewritten, with no error to notice.
• #422 — a custom-property reference cycle recurses until the stack runs out and throws RangeError out of render. CSS Variables Level 1 §3 defines the correct behaviour as guaranteed-invalid, so there's a spec answer to land on.
• #421 — an unresolved alpha corrupts the colour next to it; rgb() channels end up scaled twice.

Two are performance, and I only understood the second while measuring the first: #434 and #436 together take getStyledProps from around 1950ns to 490ns. The larger finding is that a derived observable was recomputing on every read, so the resolved-style cache wasn't serving what it cached — warm renders cost the same as cold ones. One thing that came out of measuring it, in case it's useful elsewhere: on Hermes a sort with a JS comparator is markedly more expensive than it looks on a desktop engine, since the comparator is a JS call made O(n log n) times — #434 switches the hash's ordering to a typed-array sort for that reason.

One overlaps something you'd already started, which I only spotted afterwards — sorry about the duplicated effort. #393 makes the same border-inline-* change as your fix-logical-border-props branch, and also covers the block-axis widths, the var() case and the native runtime side. Glad to rebase mine onto yours or drop whichever part you'd rather keep.

A few of them touch the same files, so the order matters:

• #434 before #436 — 436's branch already contains 434's commit, so that order keeps the second diff small.
• #390 before #430 — 430 is built on 390's branch.
• #425 before #426 — they overlap in ten files and conflict in seven the other way round.
• The rest look independent; I merge them all together locally, so I'm happy to double-check anything.

The full set, for reference: #388, #389, #390, #391, #392, #393, #410, #411, #412, #413, #415, #416, #417, #418, #420, #421, #422, #423, #425, #426, #427, #428, #429, #430, #431, #432, #434, #435, #436.

No hurry on any of this, and if anything needs changing I'm glad to do it.

[Noitidart]

Thanks for this awesome work! I think I have reported three things that might overlap with your work:

#1843
#1844
#1845

[YevheniiKotyrlo]

Thanks for the links — none of my PRs cover these three.

• #1843 — tracked upstream as #232 and fixed by #323. On main but not in a release, so 3.0.7 still crashes.
• #1845 — #397 is open with the same start/end mapping.
• #1844 — the :lang() doesn't come from react-native-css. Its lightningcss call sets no targets, and the :dir() lowering is target-driven. Tailwind's own pass is what has targets, and it excludes the feature in optimize.ts — an exclude that arrived in 4.1.0, so on a 4.0.x an upgrade may be the whole fix. (include asks lightningcss to compile a feature down, which is why adding Features.DirSelector there didn't help.)

Either way, one thing on #1844: the runtime case "dir" leaves its ltr arm unguarded, so (dir: ltr) matches in both directions. A case "lang" would get rtl: working and leave ltr: still applying in RTL.

None of these have bitten me yet, so I'd rather not promise a timeline — but once my open PRs are through I'm glad to pick up whichever are still outstanding.

[Noitidart]

Thanks very much! I have done patches in my codebase for these, I just am not sure if I did it right.

[YevheniiKotyrlo]

Yeah, I had to patch all of the issues I mentioned here, then spend significant time polishing the fixes, writing tests, and creating PRs after validating my approach locally with patches.