Troubleshooting - NativeWind

Overview

This guide covers common issues you might encounter when using NativeWind and their solutions. If you don’t find your issue here, check the GitHub issues or join our Discord.

Always start by clearing your Metro cache: npx expo start --clear or npx react-native start --reset-cache

Installation Issues

Styles not applying after installation

Problem: Installed NativeWind but styles don’t appear.Solution:

Verify installation

Check that all required packages are installed:

npm list nativewind tailwindcss react-native-css

For NativeWind v5:

package.json

{
  "dependencies": {
    "nativewind": "^5.0.0-preview.2",
    "react-native-css": "^3.0.1"
  },
  "devDependencies": {
    "tailwindcss": "^4.1.12",
    "@tailwindcss/postcss": "^4.1.11"
  }
}

Check Metro configuration

Ensure metro.config.js includes the NativeWind wrapper:

metro.config.js

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

const config = getDefaultConfig(__dirname);
module.exports = withNativewind(config);

Import global CSS

Verify you’re importing your CSS file in your app entry:

App.tsx

import "./global.css"; // Must be at the top
import { View, Text } from "react-native";

export default function App() {
  return <View className="flex-1">...</View>;
}

Clear cache and restart

# Clear Metro cache
npx expo start --clear

# Or for React Native CLI
npx react-native start --reset-cache

# Clear all caches
rm -rf node_modules/.cache

Module not found errors

Problem: Cannot find module 'nativewind/metro' or similar errors.Solution:

Delete and reinstall dependencies:

rm -rf node_modules package-lock.json yarn.lock
npm install
# or
yarn install

Check peer dependencies:
```
npm info nativewind peerDependencies
```

Ensure correct imports:

// Correct
const { withNativewind } = require("nativewind/metro");

// Incorrect
const { withNativeWind } = require("nativewind/metro");

Note: v4 uses withNativeWind, v5 uses withNativewind (lowercase ‘w’)

Peer dependency warnings

Problem: npm warns about peer dependency conflicts.Solution:NativeWind v5 requires:

tailwindcss >4.1.11
react-native-css ^3.0.1

Install exact versions:

npm install nativewind@latest
npm install --save-dev tailwindcss@latest
npm install react-native-css@latest

For v4 projects:

npm install nativewind@^4.1.23
npm install --save-dev tailwindcss@^3.4.0

Configuration Issues

Metro bundler fails to start

Problem: Metro crashes or shows configuration errors.Solutions:1. Check Metro config syntax:

metro.config.js

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

const config = getDefaultConfig(__dirname);

// Correct - export the wrapped config
module.exports = withNativewind(config);

// Incorrect - don't export before wrapping
// module.exports = config;

2. For monorepos, configure node_modules paths:

metro.config.js

const path = require("path");

config.resolver.nodeModulesPaths = [
  path.resolve(__dirname, "node_modules"),
  path.resolve(__dirname, "../../node_modules"),
];
config.watchFolders = [path.resolve(__dirname, "../../")];

3. Restart with clean cache:

npx expo start --clear

PostCSS configuration errors

Problem: PostCSS fails to process CSS or shows plugin errors.Solution:Create postcss.config.mjs (note the .mjs extension):

postcss.config.mjs

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

Install the PostCSS plugin:

npm install --save-dev @tailwindcss/postcss

NativeWind v5 requires @tailwindcss/postcss, not autoprefixer or other PostCSS plugins used with Tailwind CSS v3.

global.css not found

Problem: Error: Cannot find module './global.css'Solution:

Create the file in your project root (or src/):

global.css

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

Import with correct path:

App.tsx

import "./global.css"; // If in same directory
// or
import "../global.css"; // If in subdirectory
// or
import "./src/global.css"; // If in src folder

Include in tsconfig.json:

tsconfig.json

{
  "include": [
    "**/*.ts",
    "**/*.tsx",
    "global.css"
  ]
}

TypeScript Issues

className property not recognized

Problem: TypeScript error: Property 'className' does not exist on type 'ViewProps'Solution:

Check for nativewind-env.d.ts

Verify the file exists and contains:

nativewind-env.d.ts

/// <reference types="react-native-css/types" />

// NOTE: This file should not be edited and should be committed

Include in tsconfig.json

tsconfig.json

{
  "include": [
    "**/*.ts",
    "**/*.tsx",
    "nativewind-env.d.ts"
  ]
}

Restart TypeScript server

In VSCode: Cmd/Ctrl + Shift + P → “TypeScript: Restart TS Server”

Regenerate types

rm nativewind-env.d.ts
npx expo start --clear

Type generation disabled

Problem: nativewind-env.d.ts not being generated.Solution:Check if you disabled generation in Metro config:

metro.config.js

module.exports = withNativewind(config, {
  disableTypeScriptGeneration: false, // Should be false or omitted
});

If you manage types manually:

tsconfig.json

{
  "compilerOptions": {
    "types": [
      "react-native-css/types"
    ]
  }
}

Conflicting type declarations

Problem: Multiple declaration errors for React Native components.Solution:

Remove duplicate type references:

// Remove any manual className type declarations

Use only auto-generated types:

metro.config.js

module.exports = withNativewind(config, {
  disableTypeScriptGeneration: false,
});

Or use manual types only:

metro.config.js

module.exports = withNativewind(config, {
  disableTypeScriptGeneration: true,
});

tsconfig.json

{
  "compilerOptions": {
    "types": ["react-native-css/types"]
  }
}

Runtime Issues

Styles not updating in development

Problem: CSS changes don’t reflect in the app.Solution:

Enable Fast Refresh:

app.config.ts

export default {
  // ...
  experiments: {
    reactCompiler: false, // Disable if causing issues
  },
};

Clear Metro cache:
```
npx expo start --clear
```

Check file watching:

metro.config.js

config.watchFolders = [path.resolve(__dirname, "./")];

Reload the app manually:
- iOS Simulator: Cmd + R
- Android Emulator: R + R (double press)
- Physical device: Shake and select “Reload”

react-native-safe-area-context crash

Problem: App crashes with safe area context error.Fixed in v4.1.22: NativeWind now gracefully handles missing react-native-safe-area-context.Solution:Update to latest version:

npm install nativewind@latest

Or install safe area context:

npx expo install react-native-safe-area-context

And wrap your app:

App.tsx

import { SafeAreaProvider } from 'react-native-safe-area-context';

export default function App() {
  return (
    <SafeAreaProvider>
      {/* Your app */}
    </SafeAreaProvider>
  );
}

Windows build issues

Problem: Building fails on Windows.Fixed in v4.1.22: Windows build issues resolved.Solution:

Update to latest:
```
npm install nativewind@latest
```

Use forward slashes in paths:

metro.config.js

const path = require("path");
// Use path.resolve to handle Windows paths correctly
config.watchFolders = [path.resolve(__dirname, "./")];

Clear cache and rebuild:
```
npx expo start --clear
```

Styling Issues

Dark mode not working

Problem: Dark mode classes don’t apply.Solution:

Set userInterfaceStyle in app config:

app.config.ts

export default {
  userInterfaceStyle: "automatic", // or "light" | "dark"
};

Use dark: modifier:

<View className="bg-white dark:bg-gray-900">
  <Text className="text-black dark:text-white">Content</Text>
</View>

Check color scheme hook:

import { useColorScheme } from "react-native";

function Component() {
  const colorScheme = useColorScheme();
  console.log("Current scheme:", colorScheme);
}

Custom colors not working

Problem: Custom theme colors don’t apply.Solution for v5:Define colors in global.css using @theme:

global.css

@theme {
  --color-brand-primary: #38bdf8;
  --color-brand-secondary: #0ea5e9;
}

Usage:

<View className="bg-brand-primary">
  <Text className="text-brand-secondary">Branded</Text>
</View>

Platform modifiers not working

Problem: ios: or android: modifiers don’t work.Solution:

Verify NativeWind theme is imported:

global.css

@import "nativewind/theme"; // Required for platform modifiers

Use correct syntax:

<View className="ios:bg-blue-500 android:bg-green-500">

Test on actual platform: Platform modifiers only apply on their respective platforms.

Flexbox not working as expected

Problem: Flex layouts don’t work like web.Solution:React Native has different flexbox defaults:

{/* React Native defaults */}
<View className="flex flex-col"> {/* Default is column, not row */}

{/* To match web behavior */}
<View className="flex flex-row"> {/* Explicitly set row */}

{/* Common pattern */}
<View className="flex-1"> {/* flex: 1 is common in RN */}

React Native’s flexbox differs from web:

Default flexDirection is column (web is row)
flex: 1 is commonly used (means flex-grow: 1, flex-shrink: 1, flex-basis: 0)

Build and Production Issues

Production build fails

Problem: App builds in development but fails in production.Solution:

Clear all caches:

rm -rf node_modules/.cache
rm -rf .expo
rm -rf ios/build
rm -rf android/app/build

Rebuild native code:

# iOS
cd ios && pod install && cd ..
npx expo run:ios --configuration Release

# Android
cd android && ./gradlew clean && cd ..
npx expo run:android --variant release

Check for development-only code: Ensure no __DEV__ only styles or imports.

Large bundle size

Problem: App bundle is too large.NativeWind processes styles at build time, so unused utilities are removed automatically.Additional optimizations:

Verify tree-shaking is working: Check that unused Tailwind classes aren’t in the bundle.
Minimize custom CSS: Avoid importing large CSS files or libraries.

Analyze bundle:

npx expo export --platform ios --dev false
# Check the dist/ folder size

Debugging Tips

Enable debug logging

For the example app, debug logging is available:

DEBUG='react-native-css:*' expo start --clear

Check Metro output

Look for CSS processing logs in Metro output:

$ expo start
# Look for NativeWind/CSS processing messages

Test with inline styles

Before reporting an issue, verify the layout works with inline styles:

<View style={{ flex: 1, backgroundColor: 'blue' }}>
  {/* If this works but className doesn't, it's a NativeWind issue */}
</View>

Create minimal reproduction

Use the official templates to create reproductions:

npx rn-new@latest --nativewind

Getting Help

If you’re still experiencing issues:

GitHub Issues

Search existing issues or create a new one with a reproduction

Discord Community

Ask questions and get help from the community

Contributing

Learn how to contribute bug fixes

Documentation

Browse the full documentation

Reporting Issues

When reporting an issue, include:

NativeWind version: npm list nativewind
React Native version: Check package.json
Platform: iOS, Android, Web, or specific device
Minimal reproduction: Use npx rn-new@latest --nativewind
Steps to reproduce: Clear step-by-step instructions
Expected vs actual behavior: What you expected vs what happened
Relevant code: Metro config, global.css, component code

Issues without reproductions are likely to be closed. Always provide a minimal reproduction using the official templates.

Next Steps

Configuration

Review configuration guide

Migration

Upgrade to latest version

TypeScript

Fix TypeScript issues

Custom Styles

Learn custom styling patterns

​Overview

​Installation Issues

​Configuration Issues

​TypeScript Issues

​Runtime Issues

​Styling Issues

​Build and Production Issues

​Debugging Tips

​Getting Help

GitHub Issues

Discord Community

Contributing

Documentation

​Reporting Issues

​Next Steps

Configuration

Migration

TypeScript

Custom Styles

Overview

Installation Issues

Configuration Issues

TypeScript Issues

Runtime Issues

Styling Issues

Build and Production Issues

Debugging Tips

Getting Help

Reporting Issues

Next Steps