Configure the Babel Plugin
Control logging, ignores, and optimization behavior.
The Babel plugin (react-native-boost/plugin) is the core of React Native Boost.
Defaults are safe and usable out of the box, but you can tune behavior for your app.
Example Configuration
// babel.config.js
module.exports = {
plugins: [
[
'react-native-boost/plugin',
{
verbose: false,
silent: false,
unistyles: false,
ignores: ['node_modules/**'],
optimizations: {
text: true,
view: true,
},
},
],
],
};Plugin Options
ignores
Paths to ignore from optimization.
Patterns are resolved from Babel's current working directory. In nested monorepo apps, parent segments may be needed, for example ../../node_modules/**.
- Type:
string[] | undefined - Default:
[]
verbose
Enables verbose logging.
With silent: false, optimized components are logged by default. When enabled, skipped components and their skip reasons are also logged.
- Type:
boolean | undefined - Default:
false
silent
Disables all plugin logs.
When set to true, this overrides verbose.
- Type:
boolean | undefined - Default:
false
optimizations
Toggle individual optimizers.
If omitted, all available optimizers are enabled.
- Type:
PluginOptimizationOptions | undefined
unistyles
Enables "Unistyles mode": keep react-native-unistyles reactivity working on optimized elements.
When enabled, a Text/View whose style resolves to a Unistyles StyleSheet.create style is rewritten to Unistyles' own lean host (so its shadow-tree registration survives and theme/breakpoint/ variant updates keep working) instead of Boost's raw host; a Text/View with an unresolvable direct style (e.g. style={props.style}, a function call) is left untouched, because it could be a Unistyles style arriving from elsewhere; plain/RN styles still optimize to Boost's host as usual.
Style origin is resolved within a single file only (cross-file stylesheets count as unresolvable).
When omitted, the plugin auto-detects whether react-native-unistyles is installed and enables this if so (and logs a one-time hint to set the flag explicitly). Set to false to force it off even when Unistyles is installed.
- Type:
boolean | undefined - Default:
undefined (auto-detected)
dangerouslyOptimizeViewWithUnknownAncestors
Opt-in flag that allows View optimization when ancestor components cannot be statically resolved.
This increases optimization coverage, but may introduce behavioral differences when unresolved ancestors render React Native Text wrappers. Prefer targeted ignores first, and enable this only after verifying affected screens.
- Type:
boolean | undefined - Default:
false
dangerouslyOptimizeTextWithUnknownAncestors
Opt-in flag that allows Text optimization when ancestor components cannot be statically resolved.
This increases optimization coverage, but may introduce behavioral differences when an unresolved ancestor renders a React Native Text wrapper: a nested Text must render as the inline NativeVirtualText host rather than NativeText, and optimizing it would emit the wrong host. Prefer targeted @boost-force first, and enable this only after verifying affected screens.
- Type:
boolean | undefined - Default:
false
Plugin Optimization Options
text
Whether to optimize the Text component.
- Type:
boolean | undefined - Default:
true
view
Whether to optimize the View component.
- Type:
boolean | undefined - Default:
true
Environment-Specific Enablement
You can enable React Native Boost by environment with Babel env config:
module.exports = {
env: {
development: {
plugins: ['react-native-boost/plugin'],
},
},
};See Babel docs: https://babeljs.io/docs/options#env