Skip to main content

​
Overview

The withNativewind function configures your Metro bundler to support NativeWind styling. This is a required step for integrating NativeWind into your React Native application.

​
Installation

The Metro configuration is exported from the nativewind/metro package: 
import { withNativewind } from 'nativewind/metro';

​
Function Signature

function withNativewind<T extends MetroConfig | (() => Promise<MetroConfig>)>(
  config: T,
  options?: WithReactNativeCSSOptions
): T

​
Parameters

​
config
MetroConfig | (() => Promise<MetroConfig>)
required
Your Metro configuration object or a function that returns a Promise resolving to a Metro configuration. This can be obtained from @expo/metro-config or other Metro configuration sources.
​
options
WithReactNativeCSSOptions
Optional configuration options for customizing NativeWind behavior.

​
Returns

​
config
T
Returns the enhanced Metro configuration with NativeWind transformations applied. The return type matches the input type, preserving type safety.

​
Usage

​
Basic Setup with Expo

metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const { withNativewind } = require('nativewind/metro');

const config = getDefaultConfig(__dirname);

module.exports = withNativewind(config);

​
With Custom Options

metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const { withNativewind } = require('nativewind/metro');

const config = getDefaultConfig(__dirname);

module.exports = withNativewind(config, {
  disableTypeScriptGeneration: true,
  typescriptEnvPath: 'src/types/nativewind.d.ts',
});

​
With Async Configuration

metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const { withNativewind } = require('nativewind/metro');

const getConfig = async () => {
  const config = getDefaultConfig(__dirname);
  // Additional async configuration
  return config;
};

module.exports = withNativewind(getConfig);

​
ESM Syntax

metro.config.js
import { getDefaultConfig } from 'expo/metro-config';
import { withNativewind } from 'nativewind/metro';

const config = getDefaultConfig(import.meta.dirname);

export default withNativewind(config);

​
TypeScript Support

By default, NativeWind generates a nativewind-env.d.ts file in your project root. This file provides TypeScript definitions for the className prop on React Native components.
To use the generated types, ensure your tsconfig.json includes the file:
tsconfig.json
{
  "compilerOptions": {
    "types": ["nativewind-env"]
  }
}
If you prefer to manage types manually, disable automatic generation:
metro.config.js
module.exports = withNativewind(config, {
  disableTypeScriptGeneration: true,
});

​
How It Works

Under the hood, withNativewind wraps the withReactNativeCSS function from react-native-css/metro with NativeWind-specific defaults:
  • Enables global className polyfill for all components
  • Sets up TypeScript environment file generation
  • Configures CSS processing for React Native
The function preserves your original Metro configuration while adding the necessary transformers and resolvers for NativeWind to function.

​
Legacy API

The withNativeWind export (with capital W) is deprecated. Use withNativewind (lowercase ‘w’) instead.
// Deprecated
const { withNativeWind } = require('nativewind/metro');

// Recommended
const { withNativewind } = require('nativewind/metro');
Both exports currently work identically, but withNativeWind will be removed in a future version.

​
Troubleshooting

​
Metro bundler not picking up styles

Ensure you’ve cleared the Metro cache: 
npx expo start --clear
# or
npx react-native start --reset-cache

​
TypeScript errors with className

Verify that the nativewind-env.d.ts file exists and is included in your TypeScript configuration. You may need to restart your TypeScript server in your editor.