Babel Plugin for React Native Web Alias and Optimization

0.21.2 · active · verified Sun Apr 19

The `babel-plugin-react-native-web` package is a Babel plugin designed to optimize applications using `react-native-web`. It works by aliasing `react-native` imports to `react-native-web` and performing tree-shaking to exclude unused modules, thereby reducing bundle size. The current stable version is 0.21.2. This plugin is part of the `react-native-web` ecosystem, which generally sees frequent updates, often tied to new React and React Native versions, indicating an active development and release cadence. Its primary differentiator is enabling existing React Native codebases to run efficiently on the web without significant code changes, by providing a targeted build-time optimization layer. It's crucial for projects aiming for a single codebase across native and web platforms.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'commonjs') when configuring babel-plugin-react-native-web
```
cause The plugin configuration is malformed, or the options object is missing or not a plain object.

fix Ensure the plugin configuration is an array with the plugin name as the first element and an options object as the second element, e.g., `['react-native-web', { commonjs: false }]`.
```
Error: `react-native-web` internal paths are not stable and you must not rely on them.
```
cause Directly importing from `react-native-web/dist/exports/...` instead of `react-native` in your source code.

fix Always import components and APIs from `react-native` (e.g., `import { View, Text } from 'react-native';`). The Babel plugin will handle the internal path rewriting automatically and reliably.

Warnings

breaking React 19 support was introduced in v0.20.0, which also removed `findNodeHandle` support on web. Projects updating to v0.20.0 or higher must ensure compatibility with React 19 and deprecation of `findNodeHandle`.
Fix: Upgrade React to v19 or compatible version. Refactor code that relies on `findNodeHandle` for web, as it's no longer supported.
breaking Browser support was reduced in v0.18.0, requiring Safari 10.1+, Edge (Chromium), and dropping support for IE and legacy Android browsers. Additionally, styles are now inserted on module eval, impacting server-side rendering.
Fix: Ensure target browser matrix aligns with the new requirements. Review server-side rendering setup for style injection changes.
breaking React 18 `createRoot` support and related changes (e.g., `Animated`, `ScrollView` as Class component) were introduced in v0.19.0. Projects using React 18 must ensure their components and usages are compatible.
Fix: Upgrade React to v18 or a compatible version. Verify `Animated` and `ScrollView` implementations for React 18 compatibility.
breaking Unstable APIs had breaking changes in v0.17.0, specifically regarding `accessibilityRole='menuitem'` and `accessibilityRole='link'` behavior, and `unstable_createElement` inference. These changes affect accessibility and custom element creation.
Fix: Review and update usage of `accessibilityRole` props and `unstable_createElement` to align with the new behaviors, particularly for accessibility features.
breaking `Dimensions`, `Animated`, `VirtualizedList`, and `NativeEventEmitter` had breaking changes in v0.16.0 due to updates from React Native. `NativeEventEmitter` no longer inherits `EventEmitter`.
Fix: Update implementations relying on `Dimensions`, `Animated`, `VirtualizedList`. For `NativeEventEmitter`, replace `removeSubscription` with the subscription object's `remove()` method.
gotcha The `commonjs` option in the plugin configuration (e.g., `['react-native-web', { commonjs: true }]`) must match your bundler's module resolution strategy. Misconfiguration can lead to incorrect module resolution or larger bundles.
Fix: Set `commonjs: true` only if your bundler is configured to use CommonJS modules by default for `react-native-web` (e.g., older Webpack configs or specific module resolutions). Most modern bundlers support ES modules, so `commonjs: false` (or omitting the option) is often correct.
breaking React 17 became a peer dependency in v0.15.0. Also, `I18nManager` API changed, requiring `getConstants()` to access `isRTL` and `doLeftAndRightSwapInRTL`.
Fix: Ensure `react` and `react-dom` are at least version 17. Update `I18nManager` access patterns: `I18nManager.getConstants().isRTL`.

Install

npm install babel-plugin-react-native-web npm
yarn add babel-plugin-react-native-web yarn
pnpm add babel-plugin-react-native-web pnpm

Imports

Babel Plugin Configuration
wrong:
```
import plugin from 'babel-plugin-react-native-web'; // Incorrect usage pattern
plugins: [plugin]
```
correct:
```
plugins: [
    ["react-native-web", { commonjs: false }]
  ]
```
Babel plugins are configured in `.babelrc` or `babel.config.js` via an array, not imported like standard modules. The `commonjs` option should match your bundler's module resolution.
React Native Imports (Pre-transform)
wrong:
```
import StyleSheet from 'react-native-web/dist/exports/StyleSheet'; // Don't manually import internal paths
import View from 'react-native-web/dist/exports/View';
```
correct:
```
import { StyleSheet, View } from 'react-native';
```
The plugin's purpose is to rewrite `react-native` imports to optimized `react-native-web` paths. Developers should continue to import from `react-native` in their source code.

Quickstart

This quickstart demonstrates configuring the `babel-plugin-react-native-web` plugin in a Babel configuration file to enable aliasing and tree-shaking for React Native for Web projects.

// .babelrc or babel.config.js
module.exports = {
  presets: ['module:metro-react-native-babel-preset'], // Or other React/TypeScript presets
  plugins: [
    // ... other plugins
    ["react-native-web", {
      // Set to true if your bundler (e.g., Webpack 4 without module: false) 
      // resolves CommonJS modules by default. Most modern bundlers use ES modules.
      commonjs: false 
    }]
  ]
};

view raw JSON →