Skip to main content

​
Overview

The withUniwindConfig function configures Uniwind in your Metro bundler. This is required to enable CSS processing, type generation, and theme support in your React Native application.
All Metro configuration changes require a Metro bundler restart to take effect. Clear the cache with npx expo start --clear if you encounter issues.

​
Basic Usage

Import and wrap your Metro config with withUniwindConfig:
metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const { withUniwindConfig } = require('uniwind/metro');

const config = getDefaultConfig(__dirname);

module.exports = withUniwindConfig(config, {
  cssEntryFile: './src/global.css',
});

​
Configuration Options

​
cssEntryFile

​
cssEntryFile
string
required
The relative path to your CSS entry file from the project root. This file should contain your Tailwind imports and custom CSS.
Important: The location of your CSS entry file determines the app root - Tailwind will automatically scan for classNames starting from this directory. Files outside this directory require the @source directive in your CSS file.
Example:
metro.config.js
module.exports = withUniwindConfig(config, {
  cssEntryFile: './src/global.css',
});
Your CSS entry file should follow this structure:
global.css
@import 'tailwindcss';
@import 'uniwind';

/* Your custom CSS and themes */
Keep your CSS entry file in the root of your application folder (e.g., src, app). If you have components outside this folder, use @source to include them. See the monorepo guide for details.

​
extraThemes

​
extraThemes
Array<string>
An array of custom theme names beyond the default light and dark themes. Each theme must be defined in your CSS using the @variant directive.
Example:
metro.config.js
module.exports = withUniwindConfig(config, {
  cssEntryFile: './src/global.css',
  extraThemes: ['ocean', 'sunset', 'premium'],
});
Define these themes in your CSS:
global.css
@layer theme {
  :root {
    @variant ocean {
      --color-background: #0c4a6e;
      --color-foreground: #e0f2fe;
    }

    @variant sunset {
      --color-background: #7c2d12;
      --color-foreground: #fed7aa;
    }

    @variant premium {
      --color-background: #1e1b4b;
      --color-foreground: #fef3c7;
    }
  }
}
After adding new themes, restart your Metro bundler for changes to take effect.

Custom Themes

Learn more about creating and managing custom themes

​
dtsFile

​
dtsFile
string
The path where Uniwind will auto-generate TypeScript type definitions for your CSS classes and themes. Defaults to ./uniwind-types.d.ts in your project root.
Example:
metro.config.js
module.exports = withUniwindConfig(config, {
  cssEntryFile: './src/global.css',
  dtsFile: './src/uniwind-types.d.ts',
});
Place the .d.ts file in your src or app directory for automatic TypeScript inclusion. For custom paths outside these directories, add the file to your tsconfig.json.
TypeScript configuration:
tsconfig.json
{
  "compilerOptions": {
    // ...
  },
  "include": [
    // ...
    "./uniwind-types.d.ts"  // If placed in project root
  ]
}

​
polyfills

​
polyfills
Polyfills
Configuration for CSS unit polyfills and adjustments to ensure cross-platform consistency.

​
polyfills.rem

​
polyfills.rem
number
default:16
The base font size (in pixels) used for rem unit calculations. Defaults to 16, which is the standard browser default.
Example:
metro.config.js
module.exports = withUniwindConfig(config, {
  cssEntryFile: './src/global.css',
  polyfills: {
    rem: 14, // Change rem base to 14px
  },
});
Use case: Adjusting the rem base is useful when:
  • Your design system uses a different base font size
  • You need to scale your entire UI proportionally
  • You’re migrating from a web app with a custom rem base
  • You’re migrating from Nativewind

​
debug

​
debug
boolean
default:false
Enable debug mode to identify unsupported CSS properties and classNames. When enabled, Uniwind will log errors for web-specific CSS that doesn’t work in React Native.
Example:
metro.config.js
module.exports = withUniwindConfig(config, {
  cssEntryFile: './src/global.css',
  debug: true,
});
Debug output example: 
Uniwind Error [CSS Processor] - Unsupported value type - "filters" for className headerBlur
Enable debug mode during development if you’re experiencing styling issues or migrating from web. It helps catch web-specific CSS properties that aren’t supported in React Native.
Disable it in production builds.

​
Complete Configuration Example

Here’s a full example with all options configured:
metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const { withUniwindConfig } = require('uniwind/metro');

const config = getDefaultConfig(__dirname);

// Your custom Metro modifications
// ...

module.exports = withUniwindConfig(config, {
  // Required: Path to your CSS entry file
  cssEntryFile: './src/global.css',

  // Optional: Custom themes beyond light/dark
  extraThemes: ['ocean', 'sunset', 'premium', 'high-contrast'],

  // Optional: TypeScript definitions path
  dtsFile: './src/uniwind-types.d.ts',

  // Optional: CSS polyfills
  polyfills: {
    rem: 14, // Custom rem base size
  },

  // Optional: Enable debug mode for troubleshooting
  debug: true,
});

​
Bare React Native

For bare React Native projects (non-Expo), use the @react-native/metro-config package:
metro.config.js
const { getDefaultConfig } = require('@react-native/metro-config');
const { withUniwindConfig } = require('uniwind/metro');

const config = getDefaultConfig(__dirname);

module.exports = withUniwindConfig(config, {
  cssEntryFile: './src/global.css',
  dtsFile: './src/uniwind-types.d.ts',
});

Quickstart

Get started with Uniwind in 3 minutes

Monorepos & @source

Learn how to include components from multiple directories

Custom Themes

Create and manage custom themes beyond light and dark

Global CSS

Configure global styles and CSS variables

Theming Basics

Learn the fundamentals of theming in Uniwind