jpudysz/react-native-unistyles/unistyles-v2-to-v3-migration

Unistyles v2 to v3 Migration Skill

You are migrating a React Native codebase from react-native-unistyles v2 to v3. Follow this workflow precisely. v3 is a complete rewrite with C++ core (Nitro Modules), no re-renders, and a Babel plugin that processes StyleSheets at build time.

Prerequisites

• React Native 0.81.0+ with New Architecture mandatory (enabled by default since RN 0.76, the only architecture since RN 0.82)
• React 19+ (enforced at runtime by Unistyles)
• react-native-nitro-modules (native bridge dependency; Unistyles 3.4.0+ requires 0.37.1+)
• react-native-edge-to-edge is not needed (optional since v3.1.0, now deprecated) — set edgeToEdgeEnabled=true in android/gradle.properties instead (Expo SDK 54+ enables it automatically)
• Expo SDK 54+ (if using Expo; not compatible with Expo Go — requires dev client or prebuild)
• Xcode 16.4+ (iOS, required by Nitro Modules), iOS 15.1+

Migration Workflow

Follow these steps IN ORDER. Each step must be completed before moving to the next.

Step 1: Install v3 and configure Babel plugin

Install v3 together with Nitro Modules, then rebuild the native app (pods / Gradle):

yarn add react-native-unistyles@3 react-native-nitro-modules@0.37.1  # or npm / bun / pnpm

Add the Babel plugin:

// babel.config.js
module.exports = {
  plugins: [
    ['react-native-unistyles/plugin', { root: 'src' }]  // your app source root
  ]
}

The root option is REQUIRED (the plugin throws without it, and it can't resolve to the project root itself). Every file under root is processed, no matter what it imports. Outside root, a file is processed only if it imports react-native-unistyles, contains an import listed in autoProcessImports, or matches autoProcessPaths (which always includes the two react-native-reanimated component paths; yours are added to them). node_modules is ignored unless whitelisted via autoProcessPaths / autoRemapImports.

If using React Compiler, the Unistyles plugin MUST come BEFORE React Compiler in the plugins array.

Since 3.6.0, Metro apps can use the experimental zero-config Metro integration instead: module.exports = withUnistylesConfig(getDefaultConfig(__dirname)) with withUnistylesConfig from react-native-unistyles/metro, and no Unistyles entry in babel.config.js (having both throws). It needs no root/autoProcess* options and covers node_modules. Keep the Babel plugin for bare RN apps that list babel-plugin-react-compiler in babel.config.js plugins. The Babel plugin stays the default.

If the app is bundled with Re.Pack, don't add the plugin to babel.config.js — use RepackUnistylePlugin from react-native-unistyles/repack-plugin with unistylesPluginOptions: { root: 'src' } instead.

Step 2: Replace UnistylesRegistry with StyleSheet.configure

- import { UnistylesRegistry } from 'react-native-unistyles'
+ import { StyleSheet } from 'react-native-unistyles'
 
- UnistylesRegistry
-   .addThemes({ light: lightTheme, dark: darkTheme })
-   .addBreakpoints({ sm: 0, md: 768, lg: 1200 })
-   .addConfig({
-     adaptiveThemes: true,
-     initialTheme: 'dark',
-     plugins: [myPlugin],
-     experimentalCSSMediaQueries: true,
-     windowResizeDebounceTimeMs: 100,
-     disableAnimatedInsets: true
-   })
+ StyleSheet.configure({
+   themes: { light: lightTheme, dark: darkTheme },
+   breakpoints: { sm: 0, md: 768, lg: 1200 },
+   settings: {
+     adaptiveThemes: true // OR initialTheme: 'dark' - never both
+   }
+ })

Removed settings: plugins, experimentalCSSMediaQueries (now always on), windowResizeDebounceTimeMs (no debounce), disableAnimatedInsets (insets no longer re-render).

v3 `settings` accepts exactly: adaptiveThemes, initialTheme, CSSVars (web), nativeBreakpointsMode ('pixels' default | 'points'). Any other key throws. initialTheme together with adaptiveThemes: true throws (mutually exclusive), adaptiveThemes requires both light and dark themes, and the first breakpoint must be 0. Call StyleSheet.configure before any StyleSheet.create is evaluated (import the config file first in your entry point).

Step 3: Replace all StyleSheet imports and createStyleSheet

Unistyles StyleSheet is a full polyfill of React Native's StyleSheet — it includes hairlineWidth, compose, flatten, absoluteFill, and absoluteFillObject. You should replace all import { StyleSheet } from 'react-native' with import { StyleSheet } from 'react-native-unistyles' so you have a single import.

- import { StyleSheet } from 'react-native'
- import { createStyleSheet } from 'react-native-unistyles'
+ import { StyleSheet } from 'react-native-unistyles'
 
- const stylesheet = createStyleSheet(theme => ({
+ const styles = StyleSheet.create(theme => ({
    container: {
      backgroundColor: theme.colors.background
    }
  }))

Step 4: Remove all useStyles hooks

- import { useStyles } from 'react-native-unistyles'
 
  const MyComponent = () => {
-   const { styles, theme } = useStyles(stylesheet)
    return <View style={styles.container} />
  }

Styles created with StyleSheet.create are used directly - no hook needed. The Babel plugin handles reactivity at build time.

Dynamic functions (styles.box(width, color)) keep working, but their arguments must be serializable (strings, numbers, booleans, null, undefined, plain arrays/objects) because Unistyles stores them in C++ and re-runs the function on theme/runtime changes. Functions are dropped and Date / Map / Set / class instances become plain objects — pass precomputed values instead.

Step 5: Replace useInitialTheme with settings.initialTheme

- import { useInitialTheme } from 'react-native-unistyles'
-
- const App = () => {
-   useInitialTheme(storage.getString('preferredTheme') ?? 'light')
-   return <Stack />
- }
 
+ // In your configure call:
+ StyleSheet.configure({
+   settings: {
+     initialTheme: () => storage.getString('preferredTheme') ?? 'light'
+   }
+ })

initialTheme accepts a string or a synchronous function.

Step 6: Replace useStyles() for theme access

For components that used useStyles() (without a stylesheet) just to get theme/runtime:

Option A - withUnistyles (preferred for passing theme-derived props):

import { withUnistyles } from 'react-native-unistyles'
const UniButton = withUnistyles(Button, (theme, rt) => ({
  color: theme.colors.primary,
  size: rt.screen.width > 400 ? 'large' : 'small'
}))
// Usage: <UniButton />

Option B - useUnistyles hook (quick migration path):

import { useUnistyles } from 'react-native-unistyles'
const MyComponent = () => {
  const { theme, rt } = useUnistyles()
  return <Text style={{ color: theme.colors.primary }}>{rt.screen.width}</Text>
}

WARNING: useUnistyles re-renders the whole component whenever a theme / rt value you read changes (subscriptions are created on property access, not on destructuring). Prefer withUnistyles or StyleSheet.create(theme => ...) for performance. Note that on iOS/Android withUnistyles components always re-render on theme change. withUnistyles mappings receive the mini runtime, can't return style / contentContainerStyle (those are mapped automatically), and may return a key to force a remount.

Step 7: Update variant selection

- const { styles } = useStyles(stylesheet, { size: 'large', color: 'primary' })
+ styles.useVariants({ size: 'large', color: 'primary' })

Call styles.useVariants() at the top of your component (like a hook). It must be called before accessing styles that use variants. It always expects an object — pass {} to select default variants; styles.useVariants(undefined) throws on iOS/Android. Without a useVariants call, variants (including default) are ignored.

Step 8: Fix style spreading (CRITICAL)

v3 styles are C++ proxy objects. Spreading breaks the binding.

- <View style={{ ...styles.container, ...styles.extra }} />
+ <View style={[styles.container, styles.extra]} />
 
- <View style={{ ...styles.container, marginTop: 10 }} />
+ <View style={[styles.container, { marginTop: 10 }]} />

NEVER use {...styles.x}. ALWAYS use [styles.x, styles.y] array syntax.

Step 9: Remove plugins (use static functions in theme instead)

The plugin system is removed. Replace plugins with static functions in your theme or StyleSheet:

- // Plugin approach (v2)
- const fontPlugin: UnistylesPlugin = {
-   name: 'fontPlugin',
-   onParsedStyle: (_key, styles) => {
-     if ('fontWeight' in styles) {
-       styles.fontFamily = styles.fontWeight === 'bold' ? 'Roboto-Bold' : 'Roboto-Regular'
-     }
-     return styles
-   }
- }
 
+ // v3: Use a helper function in your theme or directly
+ const styles = StyleSheet.create(theme => ({
+   text: {
+     fontFamily: theme.utils.getFontFamily('bold')
+   }
+ }))

Step 10: Remove UnistylesProvider

UnistylesProvider no longer exists. Simply remove it from your component tree.

Step 11: Update UnistylesRuntime usage

Renamed/changed methods (follow the TypeScript types for the rest):

• UnistylesRuntime.setRootViewBackgroundColor(color?) - no more alpha parameter; accepts any React Native color, omit it to reset to transparent
• StyleSheet.hairlineWidth instead of UnistylesRuntime.hairlineWidth

Removed methods:

• addPlugin(plugin), removePlugin(plugin), enabledPlugins
• statusBar.setColor(color), navigationBar.setColor(color) (Android 15 deprecation)

v3 system bar / inset API on UnistylesRuntime:

• statusBar.setHidden(hidden, animation?) - animation is 'none' | 'fade' | 'slide' (used on iOS)
• statusBar.setStyle(style, animated?) - style is the StatusBarStyle enum (StatusBarStyle.Default | Light | Dark, exported from react-native-unistyles)
• navigationBar.setHidden(hidden) - Android only (navigation bar dimensions are always 0 on iOS)
• setImmersiveMode(enabled) - hides status + navigation bars on Android, only the status bar on iOS
• insets.ime for keyboard inset

Access system bars only through UnistylesRuntime.statusBar / UnistylesRuntime.navigationBar — there are no standalone status/navigation bar exports.

Step 12: Update TypeScript declarations

- type AppThemes = { light: typeof lightTheme, dark: typeof darkTheme }
+ type AppThemes = typeof themes  // where themes = { light: lightTheme, dark: darkTheme }
+ type AppBreakpoints = typeof breakpoints
 
  declare module 'react-native-unistyles' {
    export interface UnistylesThemes extends AppThemes {}
+   export interface UnistylesBreakpoints extends AppBreakpoints {}
  }

interface X extends typeof y is not valid TypeScript — always go through a type alias. Useful v3 exports: enums ColorScheme, Orientation, StatusBarStyle, IOSContentSizeCategory, AndroidContentSizeCategory, WebContentSizeCategory, and types UnistylesVariants, UnistylesMiniRuntime.

Step 13: Update keyboard/IME handling

- import { useAnimatedKeyboard } from 'react-native-reanimated'
- const keyboard = useAnimatedKeyboard()
 
+ // Use ime inset in StyleSheet
+ const styles = StyleSheet.create((theme, rt) => ({
+   container: {
+     paddingBottom: rt.insets.ime
+   }
+ }))

Step 14: Set up testing mocks

// package.json (or jest.config.js)
{
  "jest": {
    "setupFiles": [
      "react-native-unistyles/mocks",
      "./unistyles.ts"
    ]
  }
}

The config file (your StyleSheet.configure call) must come AFTER the mocks. The Babel plugin is a no-op when NODE_ENV=test (Jest's default). Mocks always use the first registered theme, report 0 for runtime dimensions/insets, strip variants, and render nothing for Display / Hide / ScopedTheme — don't assert on resolved styles.

Expo Router Integration