Compatibility

AniUI supports Expo SDK 53, 54, 55, Bare React Native 0.76+, NativeWind, and Uniwind. The CLI auto-detects your setup.

Version Matrix#

	Expo SDK 53/54	Expo SDK 55
NativeWind	`v4`	`v5`
Tailwind CSS	`v3`	`v4`
Reanimated	`v3`	`v4`
React	`18.x`	`19.x`
React Native	`0.79`	`0.83`
Uniwind	✅ Supported	✅ Supported
rn-primitives	✅ v1.3+	✅ v1.3+
Bare React Native	✅ 0.76+	✅ 0.83+
Architecture	Old + New	New only

How it Works#

AniUI components are source files that use className, cn(), and cva() for styling. These APIs work identically on both NativeWind v4 and v5 — the components themselves do not need to change.

What differs between versions is the project configuration: the global.css format, Tailwind config style, and template files. The AniUI CLI auto-detects your SDK version and uses the matching templates during aniui init.

Setup for Expo SDK 53/54#

# Expo SDK 53/54 — NativeWind v4 + Tailwind v3

# 1. Create project
npx create-expo-app@latest my-app --template default@sdk-54
cd my-app

# 2. Install NativeWind + dependencies
npm install nativewind tailwindcss@3 react-native-reanimated react-native-safe-area-context
npm install class-variance-authority clsx tailwind-merge

# 3. Create config files: babel.config.js, metro.config.js, tailwind.config.js, global.css
# See Installation page for exact contents

# 4. Run AniUI init (auto-detects SDK 53/54 → uses v4 templates)
npx @aniui/cli init

# 5. Import global.css at the top of app/_layout.tsx (or App.tsx)
# import "./global.css";

# 6. Clear cache and start
npx expo start -c

Uses templates/v4/ — Tailwind v3 with @tailwind directives and tailwind.config.js.

Setup for Expo SDK 55#

# Expo SDK 55 — NativeWind v5 + Tailwind v4

# 1. Create project
npx create-expo-app@latest my-app --template default@sdk-55
cd my-app

# 2. Install NativeWind v5 + dependencies
npx expo install nativewind@preview react-native-css react-native-reanimated react-native-safe-area-context
npx expo install --dev tailwindcss@4
npm install class-variance-authority clsx tailwind-merge

# 3. Create config files: babel.config.js, metro.config.js, global.css
# Note: NO tailwind.config.js or postcss.config.js — NativeWind v5 handles CSS via metro
# See Installation page for exact contents

# 4. Run AniUI init (auto-detects SDK 55 → uses v5 templates)
npx @aniui/cli init

# 5. Import global.css at the top of app/_layout.tsx (or App.tsx)
# import "./global.css";

# 6. Clear cache and start
npx expo start -c

Uses templates/v5/ — Tailwind v4 with @import "tailwindcss" and @theme directive. No separate tailwind.config.js needed.

CSS Format Differences#

SDK 53/54 (Tailwind v3)

global.css

/* Tailwind v3 / NativeWind v4 */
@tailwind base;
@tailwind components;
@tailwind utilities;

:root {
  --background: 0 0% 100%;
  /* ... theme tokens */
}

SDK 55 (Tailwind v4)

global.css

/* Tailwind v4 / NativeWind v5 */
@import "tailwindcss";
@import "nativewind/theme";

@theme {
  --color-background: hsl(var(--background));
  /* ... color mappings */
}

:root {
  --background: 0 0% 100%;
  /* ... theme tokens */
}

Migrating from SDK 53/54 to 55#

Migration steps

# 1. Update Expo SDK
npx expo install expo@~55

# 2. Install NativeWind v5 + Tailwind v4 dependencies
npx expo install nativewind@preview react-native-css react-native-reanimated react-native-safe-area-context
npx expo install --dev tailwindcss@4

# 3. Re-run aniui init to get v5 templates
npx @aniui/cli init
# This creates: global.css (with @theme block), metro.config.js, babel.config.js

# 4. Remove tailwind.config.js (no longer needed — config is in global.css)

# 5. Components — NO changes needed!
# className, cn(), cva() work identically on both versions.

Components don't change

Your AniUI components in components/ui/ work on both SDK versions without modification. Only project config files (global.css, metro.config.js) need updating.

Required Config Files#

The CLI creates all of these automatically. If styling isn't working, verify each file exists and is correct.

File	Purpose	Critical Setting
`babel.config.js`	Enables NativeWind JSX transform	`SDK 53/54: jsxImportSource: "nativewind"` `SDK 55: "nativewind/babel" plugin`
`metro.config.js`	Processes CSS with NativeWind	`withNativeWind` or `withUniwind`
`tsconfig.json`	TypeScript className support	`SDK 53/54: "nativewind"` `SDK 55: "react-native-css"`
`global.css`	Theme tokens + Tailwind directives	`--radius: 0.5rem` in :root and .dark
`tailwind.config.js`	Theme colors + NativeWind preset	SDK 53/54 only (v5 uses CSS-first config)

Known Differences#

Architecture:Expo SDK 55 dropped Old Architecture support. All apps must use New Architecture.
Reanimated:v4 requires New Architecture. If you use animated components (Tier 2), ensure New Architecture is enabled.
React 19:SDK 55 uses React 19 which changes some lifecycle behaviors. AniUI components are compatible with both React 18 and 19.
Uniwind:Uniwind uses 16px rem base (vs NativeWind's 14px). Components may appear ~14% larger. Uses withUniwind in metro.config.js instead of withNativeWind. See Uniwind guide.
rn-primitives:Overlay components (Dialog, Popover, Select, etc.) require <PortalHost /> at your app root.
React Compiler:Do NOT enable "reactCompiler": true in app.json. It breaks NativeWind's className transform, causing all styles to silently disappear.

Previous← RTL NextAndroid →