unistyles-v2-to-v3-migration（unistyles v2 到 v3 的迁移）

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.78.0+ with New Architecture mandatory (enabled by default from RN 0.83+)
• React 19+ (enforced at runtime by Unistyles)
• react-native-nitro-modules (native bridge dependency)
• react-native-edge-to-edge (required for Android edge-to-edge insets)
• Expo SDK 53+ (if using Expo; not compatible with Expo Go — requires dev client or prebuild)
• Xcode 16+ (iOS)

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 react-native-unistyles@3 and 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. It tells the plugin which directory contains your app code. Files outside this directory (except node_modules paths you explicitly configure) won't be processed.

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

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,
+     initialTheme: 'dark'
+   }
+ })

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

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.

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 causes re-renders when theme/runtime changes. Prefer withUnistyles or StyleSheet.create(theme =>...) for performance.

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.

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:

• UnistylesRuntime.setImmersiveMode(bool) replaces separate status bar/nav bar hide
• UnistylesRuntime.setRootViewBackgroundColor(color) - no more alpha parameter
• StyleSheet.hairlineWidth instead of UnistylesRuntime.hairlineWidth

Removed methods:

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

New properties on UnistylesRuntime:

• statusBar object with setHidden(hidden, animation) and setStyle(style)
• navigationBar object with setHidden(hidden)
• insets.ime for keyboard inset

Step 12: Update TypeScript declarations

- type AppThemes = { light: typeof lightTheme, dark: typeof darkTheme }
+ type AppThemes = typeof themes  // where themes = { light: lightTheme, dark: darkTheme }

  declare module 'react-native-unistyles' {
    export interface UnistylesThemes extends AppThemes {}
+   export interface UnistylesBreakpoints extends typeof breakpoints {}
  }

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

// jest.setup.js
require('react-native-unistyles/mocks')
require('./unistyles.config') // your StyleSheet.configure call

The Babel plugin auto-disables in test environments (NODE_ENV=test).

Expo Router Integration

If the project uses Expo Router, extra steps are needed because Expo Router resolves routes before Unistyles can initialize.

1. Change the main entry point in package.json:

{ "main": "index.ts" }

2. Create index.ts that imports Unistyles config before the router:

import 'expo-router/entry'
import './unistyles' // your StyleSheet.configure() file

3. For static rendering (Expo SDK 52+): import the Unistyles config in +html.tsx as well:

import '../unistyles' // ensures Unistyles initializes for each static page

import { ScrollViewStyleReset } from 'expo-router/html';
import { type PropsWithChildren } from 'react';

// This file is web-only and used to configure the root HTML for every
// web page during static rendering.
// The contents of this function only run in Node.js environments and
// do not have access to the DOM or browser APIs.
export default function Root({ children }: PropsWithChildren) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />

        {/*
          Disable body scrolling on web. This makes ScrollView components work closer to how they do on native.
          However, body scrolling is often nice to have for mobile web. If you want to enable it, remove this line.
        */}
        <ScrollViewStyleReset />

        {/* Add any additional <head> elements that you want globally available on web... */}
      </head>
      <body>{children}</body>
    </html>
  );
}

See https://www.unistyl.es/v3/guides/expo-router for full details.

Quick Reference: v2 API to v3

Decision Tree: Third-Party Components

When a third-party component needs theme values or Unistyles styles:

1. Does it accept a style prop? -> Pass Unistyles styles directly (Babel plugin handles it for standard RN components)
2. Does it need theme-derived non-style props (e.g. color)? -> Wrap with withUnistyles
3. Is it from a library with custom native views? -> Configure autoProcessPaths in Babel plugin
4. None of the above work? -> Use useUnistyles() hook as fallback

Critical Rules

1. New Architecture is mandatory - enable it explicitly (default from RN 0.83+)
2. NEVER spread styles - always use array syntax [styles.a, styles.b]
3. Babel plugin is REQUIRED - without it, styles won't be reactive
4. Import StyleSheet from react-native-unistyles only - it polyfills all RN StyleSheet APIs (hairlineWidth, compose, flatten, absoluteFill, etc.), so remove any import {StyleSheet} from 'react-native'
5. Never re-export StyleSheet from barrel files - the Babel plugin won't detect it
6. styles.useVariants() must be called before accessing styles in the component render
7. React 19+ is required - v3 uses the new React architecture

Reference Files

• For exhaustive before/after code examples: read references/migration-patterns.md
• For complete v3 API with all overloads and options: read references/v3-api-reference.md
• For troubleshooting errors and known issues: read references/common-pitfalls.md