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.
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, app, or src directory for easier path management.

​
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

​
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
  },
});

​
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

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
⌘I