Troubleshooting

Quick Diagnostic Flow

Set verbose: true and silent: false in plugin config.
Restart Metro with cache clear.
Check skip reasons in logs.
Compare with the coverage rules in Optimization Coverage.

Common Issues

No optimization logs at all

Likely causes:

Plugin not loaded in babel.config.js
silent: true
File matched by ignores

Quick checks:

module.exports = {
  plugins: [
    [
      'react-native-boost/plugin',
      {
        verbose: true,
        silent: false,
      },
    ],
  ],
};

npm start -- --clear

Skip reason: `contains blacklisted props`

This is expected for unsupported prop sets, e.g. a Text with press/responder props, selectionColor, or aria-hidden. (View translates accessibility props, tabIndex, and id instead of skipping; see Optimization Coverage.)

Fix options:

Keep component as-is (recommended when semantics matter)
Move unsupported behavior to a different node when possible
Use @boost-ignore for explicit clarity

Skip reason: `has a spread that may carry a translated prop`

A View with a spread ({...props}) Boost can't statically resolve, or that may contain a prop the View wrapper translates (aria-*, tabIndex, id).

Skip reason: `has unresolved ancestor and dangerous optimization is disabled`

A View or Text is inside an ancestor React Native Boost cannot statically classify, so it cannot prove the ancestor is not a Text (which would change the correct native host). A common case is a Text inside a third-party wrapper such as expo-router's Link (which itself wraps its children in a <Text>).

Options:

Keep default behavior (safest)
Use @boost-force on a specific line you have verified is safe
Refactor ancestor/component structure to be statically obvious
Enable dangerouslyOptimizeViewWithUnknownAncestors / dangerouslyOptimizeTextWithUnknownAncestors to override this behavior

Skip reason: `has unresolved runtime parent that may render Text`

A root Text returned by a component or renderer can be mounted inside another Text. Boost keeps the wrapper because only that wrapper can select NativeText or NativeVirtualText from the runtime context.

Use @boost-force only when every use of that component has a non-text parent. The dangerouslyOptimizeTextWithUnknownAncestors option also overrides this check.

Ignores do not work as expected in monorepos

ignores are resolved from Babel's working directory.

In nested apps, you may need explicit parent paths:

ignores: ['../../node_modules/**'];

Runtime import errors in app code

The plugin injects imports from react-native-boost/runtime.

If you installed react-native-boost as a dev dependency, runtime imports can fail in app builds.

Fix: install it as a regular dependency.

On this page