> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uniwind.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# metro.config.js

> Configure Uniwind in your Metro bundler for React Native

## 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.

<Info>
  All Metro configuration changes require a Metro bundler restart to take effect. Clear the cache with `npx expo start --clear` if you encounter issues.
</Info>

## Basic Usage

Import and wrap your Metro config with `withUniwindConfig`:

```js metro.config.js theme={null}
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

<ParamField path="cssEntryFile" type="string" required>
  The relative path to your CSS entry file from the project root. This file should contain your Tailwind imports and custom CSS.
</ParamField>

<Warning>
  **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.
</Warning>

<Warning>
  `cssEntryFile` must be a **relative path string** from project root (for example, `./src/global.css`).\
  Do not pass an absolute path or `path.resolve(...)`.
</Warning>

**Example:**

```js metro.config.js theme={null}
module.exports = withUniwindConfig(config, {
  cssEntryFile: './src/global.css',
});
```

Your CSS entry file should follow this structure:

```css global.css theme={null}
@import 'tailwindcss';
@import 'uniwind';

/* Your custom CSS and themes */
```

<Tip>
  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](/monorepos) for details.
</Tip>

### extraThemes

<ParamField path="extraThemes" type="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.
</ParamField>

**Example:**

```js metro.config.js theme={null}
module.exports = withUniwindConfig(config, {
  cssEntryFile: './src/global.css',
  extraThemes: ['ocean', 'sunset', 'premium'],
});
```

Define these themes in your CSS:

```css global.css theme={null}
@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;
    }
  }
}
```

<Warning>
  After adding new themes, restart your Metro bundler for changes to take effect.
</Warning>

<Card title="Custom Themes" icon="swatchbook" href="/theming/custom-themes">
  Learn more about creating and managing custom themes
</Card>

### dtsFile

<ParamField path="dtsFile" type="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.
</ParamField>

**Example:**

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

<Info>
  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`.
</Info>

**TypeScript configuration:**

```json tsconfig.json theme={null}
{
  "compilerOptions": {
    // ...
  },
  "include": [
    // ...
    "./uniwind-types.d.ts"  // If placed in project root
  ]
}
```

### polyfills

<ParamField path="polyfills" type="Polyfills">
  Configuration for CSS unit polyfills and adjustments to ensure cross-platform consistency.
</ParamField>

#### polyfills.rem

<ParamField path="polyfills.rem" type="number" default={16}>
  The base font size (in pixels) used for rem unit calculations. Defaults to `16`, which is the standard browser default.
</ParamField>

**Example:**

```js metro.config.js theme={null}
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

### isTV

<Badge>Available in Uniwind 1.5.0+</Badge>

<ParamField path="isTV" type="boolean" default={false}>
  Enable TV platform support for Apple TV and Android TV. When enabled, Uniwind recognizes `tv:`, `apple-tv:`, and `android-tv:` platform selectors and `@variant` directives.
</ParamField>

**Example:**

```js metro.config.js theme={null}
module.exports = withUniwindConfig(config, {
  cssEntryFile: './src/global.css',
  isTV: true,
});
```

<Info>
  When `isTV` is enabled, Uniwind maps `ios` to `apple-tv` and `android` to `android-tv` at build time. The `tv:` selector targets both TV platforms, similar to how `native:` targets both iOS and Android.
</Info>

<Card title="Platform Selectors" icon="display" href="/api/platform-select">
  Learn about TV platform selectors and focus-based styling
</Card>

### debug

<ParamField path="debug" type="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.
</ParamField>

**Example:**

```js metro.config.js theme={null}
module.exports = withUniwindConfig(config, {
  cssEntryFile: './src/global.css',
  debug: true,
});
```

**Debug output example:**

```
Uniwind Error [CSS Processor] - Unsupported value type - "filters" for className headerBlur
```

<Tip>
  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.
</Tip>

<Warning>
  Disable it in production builds.
</Warning>

## Complete Configuration Example

Here's a full example with all options configured:

```js metro.config.js theme={null}
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 TV platform support
  isTV: false,

  // 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:

```js metro.config.js theme={null}
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',
});
```

## Related

<CardGroup cols={2}>
  <Card title="Quickstart" icon="laptop" href="/quickstart">
    Get started with Uniwind in 3 minutes
  </Card>

  <Card title="Monorepos & @source" icon="folder-tree" href="/monorepos">
    Learn how to include components from multiple directories
  </Card>

  <Card title="Custom Themes" icon="swatchbook" href="/theming/custom-themes">
    Create and manage custom themes beyond light and dark
  </Card>

  <Card title="Global CSS" icon="css" href="/theming/global-css">
    Configure global styles and CSS variables
  </Card>

  <Card title="Theming Basics" icon="palette" href="/theming/basics">
    Learn the fundamentals of theming in Uniwind
  </Card>
</CardGroup>