Skip to main content

​
Step 1: Install Uniwind and Tailwind

Uniwind only supports Tailwind 4.

Installation

  bun add uniwind tailwindcss

Create global.css file

This file will serve as your CSS entry point.
@import 'tailwindcss';
@import 'uniwind';
We recommend keeping this file in the root of your project.Location matters! The location of global.css determines your app root - Tailwind will automatically scan for classNames starting from this directory. If you place global.css in a nested folder (like app/global.css), classNames in other directories won’t be detected unless you explicitly include them using the @source directive.

Import global.css file

Import the CSS file in your App.tsx (main component).
import './global.css' // <-- file from previous step

// other imports

export const App = () => {} // <-- your app's main component
Don’t import global.css in the root index.ts/index.js file where you register the Root Component, as any change will trigger a full reload instead of hot reload.
// ‼️ Don't do that
import './global.css';

import { registerRootComponent } from 'expo';
import { App } from './src';  // <- ✅ import it somewhere in the src folder

registerRootComponent(App);

​
Step 2: Configure bundler

Modify metro.config.js

If you don’t see a metro.config.js file in your project, you can create it with npx expo customize metro.config.js.
metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const { withUniwindConfig } = require('uniwind/metro'); 

const config = getDefaultConfig(__dirname);

// your metro modifications

module.exports = withUniwindConfig(config, {  
  // relative path to your global.css file (from previous step)
  cssEntryFile: './src/global.css',
  // (optional) path where we gonna auto-generate typings
  // defaults to project's root
  dtsFile: './src/uniwind-types.d.ts'
});
We recommend placing the uniwind-types.d.ts file in the src or app directory, as it will be automatically included by TypeScript. For custom paths (e.g., root of your project), please include it in your tsconfig.json.
You need to run metro server to generate typings and fix all TypeScript errors.
Important: withUniwindConfig must be the outermost wrapper in your Metro config. If you use other Metro config wrappers, make sure withUniwindConfig wraps them all.
// ✅ Correct - Uniwind wraps everything
module.exports = withUniwindConfig(
  withOtherConfig(
    withAnotherConfig(config, options),
    moreOptions
  ),
  { cssEntryFile: './src/global.css' }
);

// ❌ Wrong - Uniwind is innermost
module.exports = withOtherConfig(
  withUniwindConfig(config, { cssEntryFile: './src/global.css' }),
  options
);

​
Step 3: (Optional) Enable Tailwind IntelliSense for Uniwind

  1. Open settings.json file in your editor
  2. Add the following configuration: 
    {
    "tailwindCSS.classAttributes": [
        "class",
        "className",
        "headerClassName",
        "contentContainerClassName",
        "columnWrapperClassName",
        "endFillColorClassName",
        "imageClassName",
        "tintColorClassName",
        "ios_backgroundColorClassName",
        "thumbColorClassName",
        "trackColorOnClassName",
        "trackColorOffClassName",
        "selectionColorClassName",
        "cursorColorClassName",
        "underlineColorAndroidClassName",
        "placeholderTextColorClassName",
        "selectionHandleColorClassName",
        "colorsClassName",
        "progressBackgroundColorClassName",
        "titleColorClassName",
        "underlayColorClassName",
        "colorClassName",
        "drawerBackgroundColorClassName",
        "statusBarBackgroundColorClassName",
        "backdropColorClassName",
        "backgroundColorClassName",
        "ListFooterComponentClassName",
        "ListHeaderComponentClassName"
    ],
    "tailwindCSS.classFunctions": [
        "useResolveClassNames"
    ]
}

​
Next steps

Now that you have your Uniwind project running, explore these key features:

API documentation

Explore the complete API reference for Uniwind hooks and utilities.

Theming

Customize themes, colors, and design tokens for your React Native app.

React Native components

Style built-in React Native components with Tailwind classes.

3rd party components

Integrate Uniwind with third-party component libraries.

Monorepos & @source

Learn how to include components from multiple directories using @source.
Need help? Start a discussion on GitHub.