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,
image: false,
},
},
],
],
};Image optimization is currently opt-in because it depends on deprecated React Native import paths. Enabling it will log React Native import deprecation warnings to the console. To enable it, explicitly flip it to true:
['react-native-boost/plugin', { optimizations: { image: 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, Text and View are enabled and Image stays disabled.
- 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
dangerouslyOptimizeImageWithUnknownAncestors
Opt-in flag that allows Image 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: Android images under text render through the inline image host rather than the normal image view, and optimizing them 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
image
Whether to optimize the Image component.
Uses deprecated React Native deep imports and may print React Native deep-import deprecation warnings, so it is opt-in for now.
- Type:
boolean | undefined - Default:
false
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