Migrate react-native-unistyles from v2 to v3. Triggers on: "migrate unistyles", "upgrade unistyles", "v2 to v3", "unistyles migration", "update unistyles", "convert unistyles v2". Covers all API changes including StyleSheet.create, useStyles removal, theme configuration, variants, withUnistyles, Babel plugin setup, style spreading fixes, and third-party component wrapping.
disable-model-invocation
false
user-invocable
true
allowed-tools
Read, Grep, Glob, Edit, Write, Bash(npx *)
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+)
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
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 allimport { StyleSheet } from 'react-native' with import { StyleSheet } from 'react-native-unistyles' so you have a single import.
- 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.jsrequire('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 pageimport { ScrollViewStyleReset } from'expo-router/html';
import { typePropsWithChildren } 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.exportdefaultfunctionRoot({ children }: PropsWithChildren) {
return (
<htmllang="en"><head><metacharSet="utf-8" /><metahttpEquiv="X-UA-Compatible"content="IE=edge" /><metaname="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>
);
}
import { StyleSheet } from 'react-native-unistyles' (full polyfill)
Decision Tree: Third-Party Components
When a third-party component needs theme values or Unistyles styles:
Does it accept a style prop? -> Pass Unistyles styles directly (Babel plugin handles it for standard RN components)
Does it need theme-derived non-style props (e.g. color)? -> Wrap with withUnistyles
Is it from a library with custom native views? -> Configure autoProcessPaths in Babel plugin
None of the above work? -> Use useUnistyles() hook as fallback
Critical Rules
New Architecture is mandatory - enable it explicitly (default from RN 0.83+)
NEVER spread styles - always use array syntax [styles.a, styles.b]
Babel plugin is REQUIRED - without it, styles won't be reactive
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'
Never re-export StyleSheet from barrel files - the Babel plugin won't detect it
styles.useVariants() must be called before accessing styles in the component render
React 19+ is required - v3 uses the new React architecture
