Babel plugin

Unistyles 3.0 relies heavily on the Babel plugin, which helps convert your code in a way that allows binding the ShadowNode with Unistyles. Before reading this guide, make sure to check the Look under the hood guide.

Our golden rule is to never introduce any component that could pollute your native view hierarchy. In other words, if you use a View, it will be rendered as-is in the native view hierarchy.

Let’s discuss the responsibilities of the Babel plugin:

1. Detecting StyleSheet dependencies

Each StyleSheet is different. One might rely on a theme, another on miniRuntime, and so on. The same applies to styles. Each style depends on different things. For example, you can wrap your app in a View that safeguards your app from rendering behind the notch or navigation bar. Another style might be used in your Typography component and provides text color based on the apps’ theme.

Should the Typography style re-calculate on an insets change? Or should the View that relies on insets re-render on a theme change?

We don’t think that’s a good idea. The first responsibility of the Babel plugin is to detect all dependencies in your StyleSheet. This ensures that only the relevant styles are recalculated when necessary.

// Babel: depends on theme
const stylesheet = StyleSheet.create(theme => ({
    container: {
        // Babel: depends on theme
        backgroundColor: theme.colors.background
    },
    text: {
        // Babel: static (no dependencies)
        fontSize: 12
    }
}))

// Babel: depends on theme and miniRuntime
const stylesheet = StyleSheet.create((theme, rt) => ({
    container: {
        // Babel: depends on theme and insets
        paddingTop: rt.insets.top,
        paddingBottom: rt.insets.bottom,
        backgroundColor: theme.colors.background
    },
    text: (fontSize: number) => ({
        // Babel: depends on theme
        color: theme.colors.text,
        // Babel: depends on fontScale
        fontSize: rt.fontScale >= 3
            ? fontSize * 1.5
            : fontSize * 0.8
    })
}))

Dependency detection limitation

We put a lot of effort into making dependency detection as accurate as possible, thus we support:

• destructuring of theme and rt objects
• style’s as functions / arrow functions / objects
• nested ifs and other conditionals
• ternary operators
• logical operators
• binary operators
• and much more…

What we don’t support:

• moving functions/arrow functions out of StyleSheet.create
• theme and rt reassignment to other variables (we don’t track them)

2. Component factory (borrowing ref)

This is the most crucial part—without it, Unistyles won’t be able to update your views from C++. In the early versions of Unistyles 3.0, we tried solving this problem by using the ref prop, but it wasn’t reliable enough. Many developers use different style syntaxes, making it impossible to support all of them.

Instead, we decided to leave the user’s ref as is and transfer the implementation from Babel to our component factory. This way we have more control and we have an unified way of registering your ShadowNodes.

The component factory is a function that takes your component and renders it with an overridden ref prop:

const factory = Component => <Component ref={someMagic✨} {...props} />;

Note

We override your ref prop to connect a ShadowNode to the attached Unistyle(s). From the runtime perspective, your component will render the same way as before! We only borrow your ref momentarily to update the ShadowRegistry.

We’re also React 19–ready and will call your ref cleanup function if it’s present.

Let’s go through some examples so you can better understand how this works:

Your code

import { View } from 'react-native'

const ref = useRef()

<View ref={ref} />

Babel transform

import { View } from 'react-native-unistyles/components/native/View'

const ref = useRef()

// no changes
<View ref={ref} />

We also support other components to extract ShadowNode from them:

Your code

import { Pressable, Image } from 'react-native'

<Pressable
    ref={ref => {
        doSomething(ref)
    }}
    onPress={() => {}}
/>
<Image source={require('./image.png')} style={styles.image} ref={ref2} />

Babel transform

import { Pressable } from 'react-native-unistyles/components/native/Pressable'
import { Image } from 'react-native-unistyles/components/native/Image'

// no changes
<Pressable
    ref={ref => {
        doSomething(ref)
    }}
    onPress={() => {}}
/>
<Image source={require('./image.png')} style={styles.image} ref={ref2} />

The following react-native components are processed by the component factory: ActivityIndicator, View, Text, Image, ImageBackground, KeyboardAvoidingView, Pressable, ScrollView, FlatList, SectionList, Switch, TextInput, RefreshControl, TouchableHighlight, TouchableOpacity, VirtualizedList, Animated and SafeAreaView. Modal (no exposed native handle) and TouchableWithoutFeedback (can’t accept a ref) are not supported.

Caution

String based refs (eg. ref="myView") are not supported. The Babel plugin will throw an error if it detects one.

3. Creating scopes for stateless variants

When you use variants, each time you call useVariants, a new scope is created. This scope contains a local copy of stylesheet that won’t affect other components. This feature is similar to time travel, allowing you to explore different states of your styles with different calls to useVariants.

From your perspective, using variants is simple: you just need to call the useVariants hook:

styles.useVariants({
    size: 'small'
})

Behind the scenes, we create a scoped constant that can be accessed anywhere within the same block:

const _styles = styles
{
    const styles = _styles.useVariants({
        size: 'small'
    })

    // Your code here
}

This approach also works seamlessly with console.log, allowing you to inspect styles at any point:

// Styles without variants
console.log(styles.container)

styles.useVariants({
    size: 'small'
})

// Styles with variants: small
console.log(styles.container)

styles.useVariants({
    size: 'large'
})

// Styles with variants: large
console.log(styles.container)

By leveraging such scopes, we ensure support for any level of nesting!

Extra configuration

The Babel plugin comes with a few additional options to extend its usage.

Caution

By default babel plugin will look for any react-native-unistyles import to start processing your file. You can change this behaviour with options below:

root (required)

All files within the specified root folder will be processed by the Babel plugin. Files outside of root are processed only if they create a StyleSheet from Unistyles or import one of the autoProcessImports paths. If you need to process extra folders, use autoProcessImports or autoProcessPaths options.

{
    root: 'src' // or 'app', or any name of your root folder
}

The folder is resolved relative to Babel’s root (your project directory by default). It can’t point to the project root itself (e.g. '.'), as that would include the node_modules folder.

Note

If you use monorepo or a project with Expo Router, you most likely have multiple root folders.

In that case:

• set root to the folder containing your components eg. @myapp/ui or components
• use the autoProcessImports option to whitelist your folder (check example below)

autoProcessImports

This configuration should be used when you want to process files containing specific imports. It can be useful for monorepos that use Unistyles with absolute paths, such as @my-org/styles.

{
    autoProcessImports: ['@my-org/styles'] // whenever Babel encounters this import, it will process your file
}

autoRemapImports

This is the most powerful option, but most likely, you won’t need to use it. It allows you to remap uncommon imports to Unistyles components.

This may happen if a 3rd library does not import react-native components directly, but instead uses its own factory or a relative path. Unistyles uses it internally to support the following imports from react-native internals:

// React Native 0.83+
import { unstable_NativeText as NativeText, unstable_NativeView as NativeView } from "react-native"

// deep imports, deprecated by React Native
import { NativeText } from "react-native/Libraries/Text/TextNativeComponent"
import View from "react-native/Libraries/Components/View/ViewNativeComponent"

Note

Import the root exports with a capitalized alias, as JSX treats lowercase tags as host component names.

TypeScript declares unstable_NativeText and unstable_NativeView by default from React Native 0.87. On React Native 0.83 - 0.86 they are only part of the Strict TypeScript API, so either opt in with "customConditions": ["react-native-strict-api"] in your tsconfig.json or suppress the error with // @ts-expect-error above the import.

Let’s say you have a library called custom-library that imports react-native raw components directly:

node_modules/custom-library/components/index.js

import { NativeText } from "react-native/Libraries/Text/TextNativeComponent"
import View from "react-native/Libraries/Components/View/ViewNativeComponent"

To convert it to Unistyles, you can use the following configuration:

{
    autoRemapImports: [
        {
            path: 'node_modules/custom-library/components', // <- must be path from node_modules
            imports: [
                {
                    isDefault: false, // <- is default import?
                    name: 'NativeText', // <- if not, what's the import name?
                    path: 'react-native/Libraries/Text/TextNativeComponent', // <- what's the import source?
                    mapTo: 'NativeText' // <- which Unistyles component should be used? Check react-native-unistyles/src/components/native
                },
                {
                    isDefault: true,
                    path: 'react-native/Libraries/Components/View/ViewNativeComponent',
                    mapTo: 'NativeView'
                }
            ]
        }
    ]
}

Caution

If you use raw react-native imports within your code, Unistyles will auto map it to react-native-unistyles factories. This option should only be used for 3rd party libraries from node_modules.

autoProcessPaths

This configuration is unrelated to the root, autoProcessImports, and autoRemapImports options and can be used alongside them. By default, the Babel plugin ignores node_modules. However, you can extend these paths to attempt converting 3rd components into Unistyles compatible ones. Within these paths, we will replace react-native imports with react-native-unistyles factories that borrow component refs. Read more.

The following paths are always processed, and any paths you pass are added to this list:

[
    'react-native-reanimated/src/component',
    'react-native-reanimated/lib/module/component'
]

debug

In order to list detected dependencies by the Babel plugin you can enable the debug flag. It will console.log name of the file and component with Unistyles dependencies.

Usage with React Compiler

Check this guide for more details.

Usage in babel.config.js

You can apply any of the options above as follows:

babel.config.js

/** @type {import('react-native-unistyles/plugin').UnistylesPluginOptions} */
const unistylesPluginOptions = {
    // any component in this folder will be processed
    root: 'src',
    // also files with these imports will be processed (in any non-root folder)
    autoProcessImports: ['@react-native-ui-kit', '@my-org/styles'],
    // additionally process components from this `node_modules` package
    autoProcessPaths: ['external-library/components'],
    // log what you've found
    debug: true,
}

module.exports = function (api) {
    api.cache(true)

    return {
        // other config
        plugins: [
            ['react-native-unistyles/plugin', unistylesPluginOptions]
            // other plugins
        ]
    }
}

Usage with Re.Pack

If your app is bundled with Re.Pack, use the RepackUnistylePlugin instead of adding Unistyles to your babel.config.js. It registers an Rspack loader that runs the Unistyles Babel plugin on your files.

rspack.config.mjs

import * as Repack from '@callstack/repack'
import { RepackUnistylePlugin } from 'react-native-unistyles/repack-plugin'

export default {
    // other config
    plugins: [
        new Repack.RepackPlugin(),
        new RepackUnistylePlugin({
            // the same options as for the Babel plugin, `root` is required
            unistylesPluginOptions: {
                root: 'src'
            }
        })
    ]
}

RepackUnistylePlugin accepts the following options:

• unistylesPluginOptions – options passed to the Unistyles Babel plugin (see Extra configuration). The Babel plugin requires the root option, so you need to provide it here
• ruleExcludePaths – an array of RegExp with paths that should be skipped by the loader. Defaults to BASE_REPACK_EXCLUDE_PATHS (exported from react-native-unistyles/repack-plugin), which covers react, react-native, react-native-unistyles, react-native-nitro-modules, @callstack/repack and other core packages

Caution

The loader parses your files with @babel/plugin-syntax-typescript (.ts / .tsx files) and babel-plugin-syntax-hermes-parser (.js / .jsx files). Make sure both packages are installed in your project.