Nativewind And Tailwind Css Compatibility Skill

• NativeWind and Tailwind CSS compatibility:

• Use nativewind@2.0.11 with tailwindcss@3.3.2.

• Higher versions may cause 'process(css).then(cb)' errors.

• If errors occur, remove both packages and reinstall specific versions: npm remove nativewind tailwindcss npm install nativewind@2.0.11 tailwindcss@3.3.2

Iron Laws

• ALWAYS pin to nativewind@2.0.11 and tailwindcss@3.3.2 — higher versions trigger process(css).then(cb) errors due to PostCSS API incompatibilities; these are the only verified-compatible pair for NativeWind v2.

• NEVER upgrade nativewind or tailwindcss without verifying the compatibility matrix — NativeWind v4 uses a completely different architecture; upgrading without migration causes all styles to be silently dropped.

• ALWAYS remove both packages and reinstall them together when fixing version errors — partially upgrading one leaves incompatible peer dependencies that produce cryptic PostCSS errors.

• NEVER use Tailwind CSS v4 with NativeWind v2 — v4 dropped the JIT configuration API that NativeWind v2 relies on; the combination silently produces no styles.

• ALWAYS include nativewind/preset in tailwind.config.js — without the preset, Tailwind compiles classes but NativeWind cannot inject them into React Native's StyleSheet engine.

Anti-Patterns

Anti-Pattern Why It Fails Correct Approach

Using nativewind above 2.0.11 with tailwindcss 3.3.2 PostCSS API mismatch triggers process(css).then(cb) runtime error; styles fail silently Pin to nativewind@2.0.11

• tailwindcss@3.3.2 ; do not upgrade without migration guide

Upgrading only one of the two packages Mismatched peer dependencies cause cryptic PostCSS errors Remove both and reinstall together: npm remove nativewind tailwindcss && npm install nativewind@2.0.11 tailwindcss@3.3.2

Missing nativewind/preset in tailwind.config.js Tailwind compiles classes but NativeWind cannot inject them into React Native StyleSheet; no styles applied Add presets: [require('nativewind/preset')] to tailwind.config.js

Mixing NativeWind v2 and v4 documentation v4 uses a Babel-free architecture; v2 patterns cause crashes under v4 Decide on a single version; follow only that version's setup guide exclusively

Using Tailwind CSS v4 with NativeWind v2 v4 dropped JIT configuration API that NativeWind v2 relies on; styles silently never apply Stay on Tailwind v3 with NativeWind v2, or migrate to NativeWind v4 with Tailwind v4

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing: Record any new patterns or exceptions discovered.

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.