Skip to main content
NativeWind can be added to existing React Native projects or you can start fresh with a pre-configured template. This guide covers both approaches.
The easiest way to get started is using our pre-configured templates. Skip to Quick Start with Templates if you want to create a new project.

​
Prerequisites

NativeWind v5 requires Node.js 20 or later.
Before installing NativeWind, ensure you have:
  • Node.js >= 20
  • An existing React Native or Expo project
  • React Native >= 0.81.4 (for v5)

​
Quick Start with Templates

The fastest way to get started is using rn-new to create a pre-configured project: 
# Expo + NativeWind v5
npx rn-new@next --nativewind

# Expo + Expo Router + NativeWind v5
npx rn-new@next --nativewind --expo-router

# Expo + NativeWind v4.1 (stable)
npx rn-new@latest --nativewind
These templates come with NativeWind fully configured and ready to use.

​
Manual Installation

If you have an existing project, follow these steps to add NativeWind:
1

Install Dependencies

Install NativeWind and its peer dependencies:
npm install nativewind react-native-css tailwindcss
NativeWind v5 requires:
  • react-native-css: ^3.0.1
  • tailwindcss: >4.1.11
2

Configure Metro

Update your metro.config.js to use the NativeWind Metro plugin:
metro.config.js
const { getDefaultConfig } = require("expo/metro-config");
const { withNativewind } = require("nativewind/metro");

const config = getDefaultConfig(__dirname);

module.exports = withNativewind(config);
The withNativewind function wraps your Metro config with the necessary transformers to process Tailwind CSS classes at build time.
For advanced configuration, you can pass options to withNativewind:
metro.config.js
module.exports = withNativewind(config, {
  globalClassNamePolyfill: true,
  typescriptEnvPath: "nativewind-env.d.ts",
  disableTypeScriptGeneration: false, // Set to true to disable auto-generation
});
3

Create Global CSS File

Create a global.css file in your project root with the Tailwind directives:
global.css
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css";
@import "nativewind/theme";
This imports:
  • theme.css: Tailwind’s theme configuration
  • preflight.css: Base styles and CSS reset
  • utilities.css: All Tailwind utility classes
  • nativewind/theme: NativeWind-specific theme extensions
4

Import Global CSS

Import your global CSS file in your app’s entry point (usually App.tsx or index.js):
App.tsx
import { View, Text } from "react-native";
import "./global.css";

export default function App() {
  return (
    <View className="justify-center items-center h-full">
      <Text className="text-red-500">NativeWind is working!</Text>
    </View>
  );
}
Make sure to import the CSS file before using any className props in your components.
5

TypeScript Configuration (Optional)

NativeWind automatically generates TypeScript types for className props. A nativewind-env.d.ts file will be created in your project root:
nativewind-env.d.ts
/// <reference types="react-native-css/types" />

// NOTE: This file should not be edited and should be committed with your source code.
// It is generated by react-native-css.
This file should be committed to your repository and should not be manually edited.
To disable TypeScript generation:
metro.config.js
module.exports = withNativewind(config, {
  disableTypeScriptGeneration: true,
});

​
Platform-Specific Setup

​
Expo Projects

For Expo projects, you may need to configure your app.config.ts or app.json:
app.config.ts
import type { ConfigContext, ExpoConfig } from "expo/config";

export default ({ config }: ConfigContext): ExpoConfig => {
  return {
    ...config,
    name: "my-app",
    slug: "my-app",
    userInterfaceStyle: "automatic", // Enable automatic dark mode
  };
};

​
Bare React Native

For bare React Native projects, ensure you’re using the latest Metro version and have babel configured correctly:
babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: ["babel-preset-expo"],
  };
};

​
Verification

To verify your installation is working:
1

Start Development Server

npm start
2

Check for Build Output

You should see output indicating that NativeWind is processing your CSS:
✓ NativeWind: Processing Tailwind CSS
✓ Metro: Bundling complete
3

Test in Your App

Create a simple component with Tailwind classes:
import { View, Text } from "react-native";

export function TestComponent() {
  return (
    <View className="bg-blue-500 p-4 rounded-lg">
      <Text className="text-white font-bold">It works!</Text>
    </View>
  );
}
If you see styled components, you’re all set!

​
Troubleshooting

​
TypeScript Errors

If you see TypeScript errors about className not being a valid prop:
  1. Ensure nativewind-env.d.ts exists in your project root
  2. Restart your TypeScript server
  3. Check that the file is included in your tsconfig.json

​
Styles Not Applying

If your styles aren’t applying:
  1. Verify you’ve imported global.css in your app entry point
  2. Clear Metro bundler cache: npx expo start --clear
  3. Ensure your Metro config is properly configured with withNativewind

​
Node Version Issues

NativeWind v5 requires Node.js 20 or later. If you’re on an older version, either upgrade or use NativeWind v4.1.
Check your Node version: 
node --version
If needed, upgrade using nvm: 
nvm install 20
nvm use 20

​
Next Steps

Now that NativeWind is installed, learn how to use it:

Quick Start Tutorial

Build your first component with NativeWind

Core Concepts

Learn about how NativeWind works