React Native for Web

Common errors

• Error: Cannot find module 'react-native'

  cause The build system (Webpack/Babel) is not configured to alias 'react-native' to 'react-native-web' for the web environment.
  fix Add `babel-plugin-module-resolver` or a Webpack alias to your build configuration to map `react-native` to `react-native-web` for web builds.

• Invariant Violation: findNodeHandle is not supported on web.

  cause Attempting to use `findNodeHandle` in a `react-native-web` application, which was removed with React 19 support in v0.20.0.
  fix Remove all calls to `findNodeHandle` from your codebase targeting the web. Consider using `ref` for direct DOM access or alternative web-specific APIs.

• TypeError: (0 , react_dom__WEBPACK_IMPORTED_MODULE_2__.createRoot) is not a function

  cause This typically occurs when `react-dom` is not correctly set up for React 18's `createRoot` API, or there's a version mismatch.
  fix Ensure `react-dom` peer dependency is `^18.0.0 || ^19.0.0` and that your application entry point uses `ReactDOM.createRoot` instead of `ReactDOM.render` for React 18 and newer.

• ReferenceError: document is not defined

  cause This error often happens during server-side rendering (SSR) when client-side APIs (like `document`) are accessed in a Node.js environment.
  fix Implement proper checks (e.g., `typeof document !== 'undefined'`) around client-specific code or use a library for SSR that provides a simulated DOM environment.

Warnings

• breaking With React 19 support introduced in v0.20.0, the `findNodeHandle` API is no longer supported on the web platform.
  Fix: Avoid using `findNodeHandle` in web-targeting code; consider alternative approaches for DOM node access or refactor to use web-specific APIs where necessary.
• breaking Version 0.18.0 significantly reduced browser support, dropping compatibility for IE and legacy Android browsers. Supported browsers are Safari 10.1+, and Edge (Chromium).
  Fix: Ensure your target audience's browsers meet the new minimum requirements or consider transpilation/polyfills for broader compatibility, though full functionality is not guaranteed.
• breaking Since v0.18.0, styles are inserted on module evaluation rather than component rendering. This change affects server-side rendering, where style sheets now include styles from all evaluated modules, not just those from the initial render.
  Fix: Review server-side rendering setup to ensure correct style extraction and injection. You may need to adapt your build process to account for the earlier style insertion phase.
• breaking The `I18nManager` API was updated in v0.15.0. Properties like `isRTL` and `doLeftAndRightSwapInRTL` are no longer direct properties and must be accessed via the `getConstants()` method.
  Fix: Update usage of `I18nManager` from `I18nManager.isRTL` to `I18nManager.getConstants().isRTL`.
• gotcha Correct Babel/Webpack configuration is crucial for 'react-native' imports to resolve to 'react-native-web'. Without proper aliasing, web builds will fail.
  Fix: Ensure your build configuration (e.g., `babel-plugin-module-resolver`, Webpack aliases) is set up to alias `react-native` to `react-native-web` for web targets.

Install

• npm install react-native-web npm
• yarn add react-native-web yarn
• pnpm add react-native-web pnpm

Imports

• { View, Text, StyleSheet }
  wrong:

  import { View, Text, StyleSheet } from 'react-native-web';

  correct:

  import { View, Text, StyleSheet } from 'react-native';

  Components and APIs are imported directly from 'react-native' due to Babel/Webpack aliasing 'react-native' to 'react-native-web' in web builds.
• AppRegistry
  wrong:

  import { AppRegistry } from 'react-native-web';

  correct:

  import { AppRegistry } from 'react-native';

  Used for registering and running the main application component, following the standard React Native pattern.
• Platform

  import { Platform } from 'react-native';

  Provides platform-specific checks (e.g., Platform.OS === 'web') for conditional code execution.

Quickstart

This quickstart demonstrates a basic React Native component rendered on the web using React Native for Web, including component registration and rendering to a specified DOM element.

import React from 'react';
import { AppRegistry, StyleSheet, Text, View } from 'react-native';

class App extends React.Component {
  render() {
    return (
      <View style={styles.box}>
        <Text style={styles.text}>Hello, world!</Text>
      </View>
    );
  }
}

const styles = StyleSheet.create({
  box: { padding: 10 },
  text: { fontWeight: 'bold' }
});

AppRegistry.registerComponent('App', () => App);
AppRegistry.runApplication('App', { rootTag: document.getElementById('react-root') });