DEV Community

Cathy Lai
Cathy Lai

Posted on

How to Set Up NativeWind (Tailwind CSS) in Your Expo React Native App

#reactnative #tailwindcss #tutorial

A complete guide to adding Tailwind CSS styling to your React Native project using NativeWind

If you're coming from web development and miss the convenience of Tailwind CSS, or you're simply tired of writing verbose StyleSheet code in React Native, NativeWind is here to save the day. NativeWind brings the power of Tailwind CSS to React Native, allowing you to style your mobile apps with familiar utility classes.

In this tutorial, I'll walk you through setting up NativeWind in an Expo-managed React Native project from scratch.

Prerequisites

Before we begin, make sure you have:

  • An existing Expo React Native project
  • Node.js and npm installed
  • Basic familiarity with React Native and Tailwind CSS

Why NativeWind?

NativeWind allows you to use Tailwind's utility-first CSS approach in React Native. Instead of creating StyleSheet objects, you can write code like this:

<View className="flex-1 bg-white p-4">
  <Text className="text-2xl font-bold text-gray-800">Hello World</Text>
</View>
Enter fullscreen mode Exit fullscreen mode

Much cleaner and more maintainable than traditional StyleSheet code!

Step 1: Install Dependencies

First, install NativeWind and Tailwind CSS v3 (important: NativeWind currently only supports v3, not v4):

npm install nativewind
npm install --save-dev tailwindcss@3.3.2
Enter fullscreen mode Exit fullscreen mode

Important: Make sure to install tailwindcss@3.3.2 specifically. If you install the latest version (v4), you'll get an error saying "NativeWind only supports Tailwind CSS v3".

Step 2: Create Tailwind Configuration

Create a tailwind.config.js file in your project root:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./app/**/*.{js,jsx,ts,tsx}",
    "./components/**/*.{js,jsx,ts,tsx}",
    "./utils/**/*.{js,jsx,ts,tsx}",
  ],
  presets: [require("nativewind/preset")],
  theme: {
    extend: {},
  },
  plugins: [],
}
Enter fullscreen mode Exit fullscreen mode

The content array tells Tailwind where to look for class names in your code. Adjust these paths based on your project structure.

Step 3: Configure Metro Bundler

Create or update your metro.config.js file in the project root:

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

const config = getDefaultConfig(__dirname);

module.exports = withNativeWind(config, { input: './global.css' });
Enter fullscreen mode Exit fullscreen mode

This integrates NativeWind's transformer into Expo's Metro bundler.

Step 4: Create Global CSS File

Create a global.css file in your project root with the standard Tailwind directives:

@tailwind base;
@tailwind components;
@tailwind utilities;
Enter fullscreen mode Exit fullscreen mode

This file tells Tailwind which layers to include in your compiled CSS.

Step 5: Import Global CSS in Your Root Layout

Open your root layout file (typically app/_layout.tsx for Expo Router projects) and import the CSS file at the very top:

import "../global.css";
import { MaterialIcons } from "@expo/vector-icons";
import { Tabs } from "expo-router";

export default function RootLayout() {
  // ... rest of your layout code
}
Enter fullscreen mode Exit fullscreen mode

Important: The import must be at the top of the file, before any other imports.

Step 6: Add TypeScript Support (Optional but Recommended)

Create a nativewind-env.d.ts file in your project root to get TypeScript autocomplete for the className prop:

/// <reference types="nativewind/types" />
Enter fullscreen mode Exit fullscreen mode

This gives you full IntelliSense support for Tailwind classes in your IDE.

Step 7: Clear Cache and Start

Finally, clear the Metro cache and start your development server:

npm start -- --clear
Enter fullscreen mode Exit fullscreen mode

Or if you prefer:

npx expo start --clear
Enter fullscreen mode Exit fullscreen mode

Testing Your Setup

To verify everything works, create a simple test component:

import { View, Text } from "react-native";

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

If you see a blue screen with white text, congratulations! NativeWind is properly configured.

Using Custom Colors

You can extend Tailwind's color palette in your tailwind.config.js:

module.exports = {
  // ... other config
  theme: {
    extend: {
      colors: {
        primary: '#8C6D4A',
        secondary: '#765227',
        background: '#FFF9F3',
      },
    },
  },
}
Enter fullscreen mode Exit fullscreen mode

Then use them with bracket notation:

<View className="bg-[#FFF9F3]">
  <Text className="text-primary">Custom color text</Text>
</View>
Enter fullscreen mode Exit fullscreen mode

Common Issues and Troubleshooting

Error: "NativeWind only supports Tailwind CSS v3"

Solution: Uninstall Tailwind and reinstall version 3:

npm uninstall tailwindcss
npm install --save-dev tailwindcss@3.3.2
Enter fullscreen mode Exit fullscreen mode

Styles not applying

Solution:

  1. Make sure global.css is imported in your root layout
  2. Clear the cache: npm start -- --clear
  3. Verify your content paths in tailwind.config.js are correct

TypeScript errors on className prop

Solution: Make sure you created the nativewind-env.d.ts file and restart your TypeScript server.

Platform-Specific Styling

NativeWind supports platform-specific styles using modifiers:

<View className="ios:pt-10 android:pt-5">
  <Text>Platform-specific padding</Text>
</View>
Enter fullscreen mode Exit fullscreen mode

Conclusion

NativeWind brings the power and convenience of Tailwind CSS to React Native development. Once set up, it significantly speeds up your styling workflow and makes your code more maintainable.

The key steps are:

  1. Install NativeWind and Tailwind CSS v3
  2. Configure Tailwind and Metro
  3. Create and import global.css
  4. Start building with utility classes!

Happy styling! 🎨

Have you used NativeWind in your projects? What's your favorite feature? Let me know in the comments!

Top comments (0)