Migrate from v4

Choose the migration path

This guide targets Nativewind 5.0.0-rc.0 and react-native-css 3.1.0-rc.0 from Nativewind v4, including v4.2.7. V4 remains stable and uses Tailwind CSS 3. If you are already on v5 preview.4, follow Upgrade a v5 preview.

The RC was tested with Expo 57.0.22, React Native 0.86.3, React 19.2.3, Reanimated 4.5.1 and Worklets 0.10.1. Upgrade and verify an older Expo SDK separately. Do not force native dependency versions just to satisfy a styling migration.

NativewindUI v4 components should remain on Nativewind v4. Use their supported v4 setup instead of partially converting them to v5.

Use the migration skill

npx skills add nativewind/nativewind --skill nativewind-v4-to-v5

Ask your agent to apply the skill to your app. It includes a read only preflight, checks for custom configuration and component mappings, and recovery instructions. Review the skill and measured verification scope. Fixture results do not establish that every application is verified.

1. Preserve a working baseline

Work on a branch. Preserve your source, package manifests, lockfile and configuration, including any uncommitted work. Record the package manager and exact starting versions. Capture representative screens and interactions before editing, including themes, animations, navigation and third party components.

2. Update the dependency group together

Update Nativewind, its engine and Tailwind/PostCSS together in your manifest before installing with your existing package manager:

{
  "dependencies": {
    "nativewind": "5.0.0-rc.0",
    "react-native-css": "3.1.0-rc.0"
  },
  "devDependencies": {
    "tailwindcss": "4.1.12",
    "@tailwindcss/postcss": "4.1.12",
    "lightningcss": "1.30.1"
  }
}

Merge these entries into your existing manifest; do not replace it. Install PostCSS as shown in the installation guide, and let npx expo install align Reanimated, Worklets, safe area context and expo-system-ui with your SDK.

Nativewind RC0 requires the exact engine candidate above. The packages cannot be upgraded independently for this release. Remove direct react-native-css-interop dependencies only after checking that no application or workspace consumer still needs them.

If npm reports ERESOLVE from the stale v4/Tailwind 3 graph, do not use --force or --legacy-peer-deps. Follow the tested recovery procedure, which saves the intended manifest and lets npm update the styling dependency group without deleting the lockfile. Workspaces require a consumer inventory first.

3. Convert Tailwind configuration

Translate custom theme values, plugins and utilities to Tailwind 4 CSS configuration. Preserve any customizations that do not have a verified replacement. Review the Tailwind upgrade guide; utility renames alone do not prove the same native appearance.

Replace the Tailwind 3 directives in your root CSS:

@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css";
@import "nativewind/theme";

Keep utilities unlayered so React Native Web defaults do not override them. Add @source paths for shared workspace components when needed.

Create or update postcss.config.mjs, preserving unrelated plugins:

export default { plugins: { "@tailwindcss/postcss": {} } };

Expo 57 does not discover postcss.config.cjs. Follow the installation guide to pin lightningcss 1.30.1 through your package manager's overrides or resolutions.

4. Update Babel, Metro and TypeScript

Remove nativewind/babel and the Nativewind jsxImportSource setting from the v4 setup. Keep babel-preset-expo and unrelated plugins.

const { getDefaultConfig } = require("expo/metro-config");
const { withNativewind } = require("nativewind/metro");
 
module.exports = withNativewind(getDefaultConfig(__dirname));

Wrap your existing Metro config rather than discarding custom resolvers. The v4 input option is no longer needed. Import the root CSS once in App.tsx or app/_layout.tsx. Ensure the generated nativewind-env.d.ts belongs to your TypeScript project.

5. Review application contracts

Use styled for components that need explicit mapping. The RC does not export cssInterop or remapProps from Nativewind. Do not mechanically rename those functions: styled returns a wrapper that must be used, and prop destinations and precedence need to be checked. There is no global option. nativeStyleMapping is the current mapping option; nativeStyleToProp remains a deprecated alias.

For native theme overrides, use Appearance.setColorScheme("dark") or "light". On the Expo 57 target, "unspecified" restores system appearance. Set expo.userInterfaceStyle to "automatic". Preserve any custom browser theme selection separately. See Dark Mode.

Prefer VariableContextProvider for runtime variables and exclude variables that must remain dynamic from compiler inlining. Cross platform lengths need units, for example "80px". vars(), the Nativewind color scheme hook and useUnstableNativeVariable remain available; deprecated does not mean removed.

Remove legacy @cssInterop or @react-native configuration after translating its intent. Qualified native root selectors such as :root.dark are rejected; use media queries and Appearance on native.

Props such as placeholderClassName, indicatorClassName, presentationClassName, cssInterop and StatusBar className no longer have declarations for unsupported v5 mappings. Use native props or explicit supported wrappers. TextInput supports className="placeholder:text-gray-500".

Shadows now use React Native boxShadow, and animations use Reanimated CSS animations. Compare the affected screens with your baseline. See the RC compatibility guide for value and platform limits, including the known Android animation cancellation issue.

6. Verify and recover

Restart Metro with npx expo start --clear. Rebuild native apps when native dependencies or configuration change. Run typechecks and production bundles, then compare actual rendering and interactions on every supported platform. Include theme override and system restoration, mappings, text entry, navigation and animations.

A successful export does not prove visual parity. Report unavailable or failing runtime checks as verification pending. A second migration pass should make no new source or dependency changes.

To revert, restore only this migration's changes from your source, manifest, lockfile and configuration snapshots. Reinstall with the same package manager and rebuild if native dependencies changed. Preserve unrelated user work.