{"id":10542,"library":"babel-plugin-react-native-web","title":"Babel Plugin for React Native Web Alias and Optimization","description":"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.","status":"active","version":"0.21.2","language":"javascript","source_language":"en","source_url":"git://github.com/necolas/react-native-web","tags":["javascript"],"install":[{"cmd":"npm install babel-plugin-react-native-web","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-react-native-web","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-react-native-web","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This plugin aliases imports to `react-native-web`, which must be installed as a peer/runtime dependency of the project.","package":"react-native-web","optional":false},{"reason":"React is a peer dependency of `react-native-web` (v0.15+ requires React 17+, v0.19+ supports React 18, v0.20+ supports React 19).","package":"react","optional":false},{"reason":"As a Babel plugin, Babel itself is required for its operation.","package":"@babel/core","optional":false}],"imports":[{"note":"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.","wrong":"import plugin from 'babel-plugin-react-native-web'; // Incorrect usage pattern\nplugins: [plugin]","symbol":"Babel Plugin Configuration","correct":"plugins: [\n    [\"react-native-web\", { commonjs: false }]\n  ]"},{"note":"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.","wrong":"import StyleSheet from 'react-native-web/dist/exports/StyleSheet'; // Don't manually import internal paths\nimport View from 'react-native-web/dist/exports/View';","symbol":"React Native Imports (Pre-transform)","correct":"import { StyleSheet, View } from 'react-native';"}],"quickstart":{"code":"// .babelrc or babel.config.js\nmodule.exports = {\n  presets: ['module:metro-react-native-babel-preset'], // Or other React/TypeScript presets\n  plugins: [\n    // ... other plugins\n    [\"react-native-web\", {\n      // Set to true if your bundler (e.g., Webpack 4 without module: false) \n      // resolves CommonJS modules by default. Most modern bundlers use ES modules.\n      commonjs: false \n    }]\n  ]\n};","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade React to v19 or compatible version. Refactor code that relies on `findNodeHandle` for web, as it's no longer supported.","message":"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`.","severity":"breaking","affected_versions":">=0.20.0"},{"fix":"Ensure target browser matrix aligns with the new requirements. Review server-side rendering setup for style injection changes.","message":"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.","severity":"breaking","affected_versions":">=0.18.0"},{"fix":"Upgrade React to v18 or a compatible version. Verify `Animated` and `ScrollView` implementations for React 18 compatibility.","message":"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.","severity":"breaking","affected_versions":">=0.19.0"},{"fix":"Review and update usage of `accessibilityRole` props and `unstable_createElement` to align with the new behaviors, particularly for accessibility features.","message":"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.","severity":"breaking","affected_versions":">=0.17.0"},{"fix":"Update implementations relying on `Dimensions`, `Animated`, `VirtualizedList`. For `NativeEventEmitter`, replace `removeSubscription` with the subscription object's `remove()` method.","message":"`Dimensions`, `Animated`, `VirtualizedList`, and `NativeEventEmitter` had breaking changes in v0.16.0 due to updates from React Native. `NativeEventEmitter` no longer inherits `EventEmitter`.","severity":"breaking","affected_versions":">=0.16.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `react` and `react-dom` are at least version 17. Update `I18nManager` access patterns: `I18nManager.getConstants().isRTL`.","message":"React 17 became a peer dependency in v0.15.0. Also, `I18nManager` API changed, requiring `getConstants()` to access `isRTL` and `doLeftAndRightSwapInRTL`.","severity":"breaking","affected_versions":">=0.15.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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 }]`.","cause":"The plugin configuration is malformed, or the options object is missing or not a plain object.","error":"TypeError: Cannot read properties of undefined (reading 'commonjs') when configuring babel-plugin-react-native-web"},{"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.","cause":"Directly importing from `react-native-web/dist/exports/...` instead of `react-native` in your source code.","error":"Error: `react-native-web` internal paths are not stable and you must not rely on them."}],"ecosystem":"npm"}