Configure Boost

Example Configuration

Pass options to withBoostConfig in your Metro config.

// metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const { withBoostConfig } = require('react-native-boost/metro');

module.exports = withBoostConfig(getDefaultConfig(__dirname), {
  logLevel: 'debug',
  ignores: ['node_modules/**'],
  integrations: {
    unistyles: 'on',
  },
  optimizations: {
    'native-activity-indicator': 'off',
  },
});

If you're using a custom resolver.resolveRequest that redirects react-native to a different installation, you may need to set the React Native package path explicitly:

withBoostConfig(config, {
  target: { reactNative: { packageJson: require.resolve('react-native/package.json') } },
});

Babel config

Boost 2 does not need Babel configuration when you use Metro. For other bundlers, see the non-Metro setup guide.

Resolves imported component ancestors through Metro's module graph. This uses private/internal Metro APIs until Metro supports cross-file transform inputs (https://github.com/react/metro/issues/1902). Set this to false to use same-file ancestor analysis only.

Type: boolean | undefined
Default: true in supported Metro versions

`optimizations`

Configures individual optimizations.

Type: PluginOptimizationOptions | undefined

`assumptions`

Declares project-wide facts that enable additional optimizations.

Type: PluginAssumptions | undefined

`integrations`

Configures supported third-party libraries.

Type: PluginIntegrationOptions | undefined

`ignores`

Paths to ignore from optimization.

Type: string[] | undefined

`logLevel`

Controls plugin logging.

Type: LogLevel | undefined

`target`

Supplies the React Native target when automatic detection is unsuitable.

Type: { reactNative?: ReactNativeTargetOption; } | undefined

Optimization Options

Set an optimization to on or off. Omitted entries use their defaults.

`native-text`

Replaces the React Native Text wrapper with its native host.

Type: OptimizationSetting<never> | undefined
Default: 'on'

`native-view`

Replaces the React Native View wrapper with its native host.

Type: OptimizationSetting<never> | undefined
Default: 'on'

`native-image`

Replaces the React Native Image wrapper with its native host.

Type: OptimizationSetting<never> | undefined
Default: 'on'

`native-activity-indicator`

Replaces the React Native ActivityIndicator wrapper with its native hosts.

Type: OptimizationSetting<never> | undefined
Default: 'on'

`animated-value-initialization`

Creates persistent Animated values lazily instead of recreating unused values on each render.

Type: OptimizationSetting<never> | undefined
Default: 'on' for detected RN 0.83+

`animated-wrapper-removal`

Removes built-in Animated wrappers whose props contain no animated values.

Type: OptimizationSetting<never> | undefined
Default: 'on' for RN 0.83–0.86, 'off' otherwise

`stylesheet-operations`

Evaluates static React Native StyleSheet operations at build time.

Type: OptimizationSetting<never> | undefined
Default: 'on'

`platform-folding`

Folds React Native Platform.select calls and Platform.OS branches at build time.

Type: OptimizationSetting<never> | undefined
Default: 'on'

Assumptions

Assumptions let Boost optimize code that static analysis cannot prove safe.

Verify assumptions

A false assumption can change runtime behavior. Make sure you know what you're doing.

`unknownAncestorsDoNotRenderText`

Assume unresolved ancestors and runtime parents do not provide a React Native Text context.

This increases optimization coverage, but can emit the wrong native host when the assumption is false. Enable it only after you verify this behavior across the project.

Type: boolean | undefined
Default: false

Integration Options

`uniwind`

Preserves free Uniwind 1.12.x styles on optimized components. Requires Metro. auto detects an active withUniwindConfig. Apply withBoostConfig after it. on requires that configuration. Use off only when transformed code does not use Uniwind.

Type: IntegrationState | undefined
Default: 'auto'

`unistyles`

Keeps react-native-unistyles reactivity working on optimized elements.

auto detects an installed react-native-unistyles package and logs a warning when found. Use on when the project uses Unistyles, or off when the package is installed but not used in transformed code.

Type: IntegrationState | undefined
Default: 'auto'