Skip to main content

​
Overview

NativeWind requires configuration in three key areas: Metro bundler, Babel transpiler, and Tailwind CSS. This guide walks you through setting up each component for optimal performance.
NativeWind v5 uses react-native-css under the hood and processes styles at build time for better performance.

​
Metro Configuration

Metro is React Native’s JavaScript bundler. NativeWind provides a wrapper function that configures Metro for CSS processing.
1

Install dependencies

First, ensure you have the required peer dependencies:
npm install nativewind@latest
npm install --save-dev tailwindcss@latest
npm install react-native-css@latest
NativeWind requires tailwindcss >4.1.11 and react-native-css ^3.0.1
2

Configure Metro

Wrap your Metro config with withNativewind:
metro.config.js
const { getDefaultConfig } = require("expo/metro-config");
const { withNativewind } = require("nativewind/metro");

const config = getDefaultConfig(__dirname);

module.exports = withNativewind(config);
metro.config.js
const { getDefaultConfig, mergeConfig } = require("@react-native/metro-config");
const { withNativewind } = require("nativewind/metro");

const config = getDefaultConfig(__dirname);

module.exports = withNativewind(config);
3

Configure with options

The withNativewind function accepts options to customize behavior:
metro.config.js
const { withNativewind } = require("nativewind/metro");
const config = getDefaultConfig(__dirname);

module.exports = withNativewind(config, {
  // Disable TypeScript type generation
  disableTypeScriptGeneration: false,
  // Custom path for TypeScript environment file
  typescriptEnvPath: "nativewind-env.d.ts",
  // Enable global className polyfill
  globalClassNamePolyfill: true,
});
​
disableTypeScriptGeneration
boolean
default:"false"
Set to true to disable automatic generation of nativewind-env.d.ts
​
typescriptEnvPath
string
default:"nativewind-env.d.ts"
Custom path for the TypeScript environment declaration file
​
globalClassNamePolyfill
boolean
default:"true"
Enables the className prop on all React Native components

​
Babel Configuration

Babel transforms your JavaScript code. NativeWind’s Babel plugin is re-exported from react-native-css.
1

Update babel.config.js

For Expo projects, use babel-preset-expo:
babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: [["babel-preset-expo"]],
  };
};
The NativeWind Babel plugin is automatically included through the Metro configuration. You don’t need to add it manually.
2

For React Native CLI

babel.config.js
module.exports = {
  presets: ['module:@react-native/babel-preset'],
};

​
Tailwind CSS Configuration

NativeWind v5 uses Tailwind CSS v4’s new CSS-based configuration system.
1

Create global CSS file

Create a global.css file in your project root (or src/ directory):
global.css
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css";
@import "nativewind/theme";
  • tailwindcss/theme.css - Defines theme tokens (colors, spacing, etc.)
  • tailwindcss/preflight.css - Base styles and resets
  • tailwindcss/utilities.css - Utility classes (text-red-500, flex, etc.)
  • nativewind/theme - React Native-specific utilities and platform modifiers
2

Import in your app entry

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

export default function App() {
  return (
    <View className="justify-center items-center h-full">
      <Text className="text-red-500">Hello NativeWind!</Text>
    </View>
  );
}
3

Configure PostCSS

Create a postcss.config.mjs file:
postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};
Install @tailwindcss/postcss as a dev dependency: npm install --save-dev @tailwindcss/postcss

​
Platform-Specific Configuration

NativeWind includes platform-specific utilities and modifiers.

​
Platform Modifiers

Use platform modifiers to apply styles conditionally: 
<View className="ios:bg-blue-500 android:bg-green-500 web:bg-red-500">
  <Text className="native:text-white web:text-black">Platform-specific styles</Text>
</View>

<Text className="ios:font-system android:font-roboto">
  Platform fonts
</Text>

​
Custom Theme Configuration

Extend the default theme using CSS custom properties:
global.css
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css";
@import "nativewind/theme";

@theme {
  /* Custom elevation tokens */
  --elevation-xs: 1;
  --elevation-sm: 3;
  --elevation-md: 6;
  --elevation-lg: 8;
  --elevation-xl: 13;
  --elevation-2xl: 24;
  --elevation-none: 0;

  /* Custom colors */
  --color-brand-primary: #38bdf8;
  --color-brand-secondary: #0ea5e9;
}

:root {
  @media ios {
    --font-sans: System;
    --font-serif: Georgia;
    --font-mono: Menlo;
  }

  @media android {
    --font-sans: SystemAndroid;
    --font-serif: sans-serif;
    --font-mono: monospace;
  }
}

​
Advanced Configuration

​
Monorepo Setup

For monorepo setups, configure Metro to resolve node_modules correctly:
metro.config.js
const path = require("path");
const { getDefaultConfig } = require("expo/metro-config");
const { withNativewind } = require("nativewind/metro");

const config = getDefaultConfig(__dirname);

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

module.exports = withNativewind(config);

​
Disabling TypeScript Generation

If you manage types through compilerOptions.types, disable auto-generation:
metro.config.js
module.exports = withNativewind(config, { 
  disableTypeScriptGeneration: true 
});

​
Verification

Verify your configuration is working:
1

Check generated types

After running your dev server, verify nativewind-env.d.ts was created:
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.
2

Test styles

Create a simple component to verify styles work:
import { View, Text } from "react-native";

export default function Test() {
  return (
    <View className="flex-1 items-center justify-center bg-blue-500">
      <Text className="text-white text-2xl font-bold">
        NativeWind is working!
      </Text>
    </View>
  );
}
3

Check Metro output

Look for CSS processing logs in your Metro bundler output:
$ expo start --clear
Always clear your Metro cache when making configuration changes:
expo start --clear
# or
react-native start --reset-cache

​
Next Steps

TypeScript Setup

Configure TypeScript for type safety with NativeWind

Custom Styles

Learn to create custom utilities and components

Troubleshooting

Common issues and solutions

Tailwind Plugin

API reference for the Tailwind plugin