AniUI

Installation

Get AniUI set up in your React Native project in under 2 minutes.

One command setup

The CLI auto-detects your project type (Expo/Bare RN), SDK version, and package manager. It installs missing dependencies, creates config files, and sets up theming — all in one step.

Step 1. Create a React Native project (if you don't have one)#

# Expo (recommended)
npx create-expo-app@latest my-app
cd my-app

# Or Bare React Native
npx @react-native-community/cli init MyApp
cd MyApp

Step 2. Run AniUI init#

The CLI will ask you to choose NativeWind or Uniwind, a theme preset, and where to put components. It then automatically installs all required dependencies.

npx @aniui/cli init

# Or with a specific styling engine:
npx @aniui/cli init --style uniwind

The CLI will:

  • 1. Detect your project type, SDK version, and package manager
  • 2. Ask: NativeWind or Uniwind? Theme preset? TypeScript?
  • 3. Install missing packages (nativewind/uniwind, tailwindcss, reanimated, cva, clsx, etc.)
  • 4. Create metro.config.js, babel.config.js, tailwind.config.js, global.css
  • 5. Update tsconfig.json with correct jsxImportSource
  • 6. Disable React Compiler if enabled (breaks NativeWind)
  • 7. Create lib/utils.ts and components/ui/ directory

Step 3. Import global.css#

Add this import at the very top of your app entry file:

app/_layout.tsx (or App.tsx)
import "./global.css";
// ... rest of your app

Step 4. Add components and start#

npx @aniui/cli add button text input card

# Start with clean cache
npx expo start -c

That's it. Components are copied to your components/ui/ directory. You own the source code — customize freely.

Overlay components (Dialog, Popover, Select, etc.)

Components using @rn-primitives need <PortalHost /> in your root layout. Add it as the last child inside your root wrapper:

import { PortalHost } from "@rn-primitives/portal";

// In your root layout:
<GestureHandlerRootView style={{ flex: 1 }}>
  <Stack />
  <PortalHost />
</GestureHandlerRootView>

If you prefer to install dependencies yourself or need platform-specific guidance.

Troubleshooting#

Run the diagnostic first

Before debugging manually, run npx @aniui/cli doctor — it checks every dependency, config file, and known conflict, and tells you exactly what to fix.

Styles not appearing / components render unstyled

  • 1. Expo SDK 53/54: Check babel.config.js has jsxImportSource: "nativewind" in babel-preset-expo options
  • 1. Expo SDK 55: babel.config.js must NOT have jsxImportSource or nativewind/babel — withNativeWind in metro handles everything
  • 1. Bare RN: Check babel.config.js has nativewind/babel in presets
  • 2. Check metro.config.js wraps config with withNativeWind
  • 3. Check global.css is imported at the top of your app entry file
  • 4. Clear Metro cache: npx expo start -c or npm start -- --reset-cache

SDK 55: "Unable to resolve nativewind/jsx-dev-runtime"

Remove jsxImportSource: "nativewind" from both babel.config.js and tsconfig.json. NativeWind v5 does not use jsxImportSource — it handles className via metro import rewriting.

SDK 55: "Invalid call: process.env.EXPO_ROUTER_APP_ROOT"

Install babel-preset-expo as a devDependency in your project: npx expo install --dev babel-preset-expo. In monorepos, the wrong version may be hoisted from another package.

SDK 55: lightningcss "failed to deserialize" error

Add "overrides": { "lightningcss": "1.30.1" } to package.json and run npm install.

SDK 55: Theme colors not working (hsl(var(...)) returns transparent)

NativeWind v5's CSS compiler cannot resolve hsl(var(--color)) at build time. Use direct values in the @theme block instead: --color-primary: hsl(240 5.9% 10%)

SDK 55: className on SafeAreaView doesn't work

NativeWind v5 only wraps core react-native components. Third-party components like SafeAreaView from react-native-safe-area-context need style instead of className for layout props like flex.

Bare RN: "Unable to resolve nativewind/metro"

Make sure nativewind is installed as a dependency (not just devDependency). Run npm install nativewind and restart Metro with --reset-cache.

Bare RN: Reanimated crash on app launch

Ensure react-native-reanimated/plugin is the last plugin in your babel.config.js plugins array. Then run cd ios && pod install and rebuild.

React Compiler breaks NativeWind

Remove "reactCompiler": true from app.json → expo.experiments. It interferes with NativeWind's className JSX transformation.

Property 'className' does not exist

Create nativewind-env.d.ts in your project root with: /// <reference types="nativewind/types" />

SDK Compatibility →Browse Components →
Previous← IntroductionNextJavaScript →