# React Native Package Structure Explained: A Deep Dive into the Monorepo Architecture

> Explore the React Native package structure and monorepo architecture. Understand how core runtime and utilities are organized in the facebook/react-native repository.

- Repository: [Meta/react-native](https://github.com/facebook/react-native)
- Tags: deep-dive
- Published: 2026-02-25

---

**React Native organizes its entire framework, tooling, and utilities as a Yarn workspaces monorepo under the `packages/` directory, with the core runtime residing in `packages/react-native` and standalone utilities like Metro configs, Babel presets, and Jest configurations distributed as separate npm modules.**

The React Native repository on GitHub (`facebook/react-native`) follows a monorepo pattern that enables independent versioning of utilities while maintaining tight integration between the core framework and its build toolchain. Understanding this React Native package structure is essential for contributors debugging native code and developers customizing their build pipeline.

## Monorepo Architecture Overview

React Native uses **Yarn workspaces** to manage dependencies across multiple packages from a single root [`package.json`](https://github.com/facebook/react-native/blob/main/package.json). The workspace configuration declares all sub-packages under the `packages/*` glob pattern:

```json
// https://github.com/facebook/react-native/blob/main/package.json
{
  "private": true,
  "workspaces": [
    "packages/*"
  ]
}

```

This setup allows `react-native` to import `react-native-codegen` directly during development without publishing to npm first, while still enabling each package to be published independently under the `react-native-*` scope when appropriate.

## Core Package Structure

### The Main react-native Package

The primary framework code lives in **`packages/react-native/`**. This package contains the JavaScript bridge, native modules, UI components, and platform-specific native implementations for Android and iOS.

Key subdirectories within the core package:

- **`ReactAndroid/`** – Java and C++ sources for the Android native implementation
- **`ReactCommon/`** – Shared C++ code used by both Android and iOS native layers
- **`Libraries/`** – JavaScript source files for components and APIs (e.g., [`Libraries/Components/Text/Text.js`](https://github.com/facebook/react-native/blob/main/Libraries/Components/Text/Text.js))
- **`android/`** and **`ios/`** – Platform-specific native module configurations

### Native Code Organization

The native architecture separates platform-specific code from shared C++ logic:

- **Android**: `packages/react-native/ReactAndroid/` contains Java packages (`com.facebook.react`) and JNI bindings to C++ code
- **iOS**: Native code resides in `packages/react-native/React/` and `packages/react-native/ReactCommon/` (shared with Android via C++)
- **Shared C++**: `ReactCommon/` houses the TurboModule system, Fabric renderer, and core runtime logic used across both platforms

## Tooling and Build Packages

### Metro Integration

React Native distributes its Metro bundler configuration as standalone packages:

- **`packages/metro-config/`** – Default Metro configuration used by all React Native apps, exporting `getDefaultConfig()` for customization
- **`packages/metro-runtime/`** – Runtime helpers injected by Metro into the JavaScript bundle during bundling

Developers customize their bundling pipeline by extending the default config:

```javascript
// metro.config.js – placed at the root of your RN app
const { getDefaultConfig } = require('metro-config');

module.exports = (async () => {
  const {
    resolver: { sourceExts, assetExts },
  } = await getDefaultConfig();

  return {
    transformer: {
      babelTransformerPath: require.resolve('react-native-babel-transformer'),
    },
    resolver: {
      assetExts: assetExts.filter(ext => ext !== 'svg'),
      sourceExts: [...sourceExts, 'svg'],
    },
  };
})();

```

### Babel and Code Generation

The build pipeline relies on specialized Babel and code generation packages:

- **`packages/react-native-babel-preset/`** – Babel preset compiling RN-specific syntax (JSX, Flow, TypeScript)
- **`packages/react-native-babel-transformer/`** – Transformer implementation used by Metro
- **`packages/react-native-codegen/`** – Generates typed native module code from Flow/TypeScript definitions, creating the TurboModule bindings between JavaScript and native code

### Testing Infrastructure

React Native provides pre-configured testing utilities:

- **`packages/jest-preset/`** – Jest preset configured for React Native component testing, including module name mapping and transform settings
- **`packages/eslint-plugin-react-native/`** – ESLint rules enforcing RN-specific best practices
- **`packages/eslint-config-react-native/`** – Shareable ESLint configuration

Example Jest configuration:

```javascript
// jest.config.js
module.exports = {
  preset: 'react-native',
  setupFiles: ['./jest/setup.js'],
  transformIgnorePatterns: [
    'node_modules/(?!(react-native|my-project|react-native-codegen)/)',
  ],
};

```

## Development and Debugging Utilities

Several packages support the development workflow and debugging:

- **`packages/dev-middleware/`** – Development server middleware handling hot reloading, symbolication, and debugging protocol translation
- **`packages/debugger-shell/`** – Backend debugger shell used by Flipper and React Native Debugger
- **`packages/debugger-frontend/`** – Frontend UI components for the debugging interface
- **`packages/community-cli-plugin/`** – Implements community-driven CLI commands such as `react-native-clean-project`

## Standalone Utility Packages

React Native extracts certain utilities as standalone packages to allow usage without importing the entire framework:

- **`packages/virtualized-lists/`** – Standalone implementation of `FlatList`, `SectionList`, and `VirtualizedList` that can be consumed independently of the core native bridge

This enables library authors to use React Native's list virtualization logic in web projects or other React environments without pulling in native module dependencies.

## Build Process and Code Generation

The React Native package structure supports a sophisticated build pipeline orchestrated through the root `scripts/` directory:

1. **Codegen Phase** – `react-native-codegen` scans Flow/TypeScript definitions in `packages/react-native/Libraries/` and generates native binding code for TurboModules and Fabric components
2. **Babel Transformation** – `react-native-babel-transformer` compiles modern JavaScript, JSX, and Flow types to ES5 compatible code
3. **Metro Bundling** – `metro-config` provides the bundler configuration that packages JavaScript and assets for deployment
4. **Package Preparation** – Each package's `prepare` script compiles source code into distribution folders before npm publishing

This modular architecture allows the React Native team to version and release tooling independently from the core framework runtime.

## Summary

- React Native uses a **Yarn workspaces monorepo** with all publishable code under `packages/`
- The **core framework** resides in `packages/react-native/`, containing JavaScript libraries (`Libraries/`), Android native code (`ReactAndroid/`), and shared C++ code (`ReactCommon/`)
- **Build tooling** is modularized into separate packages: `metro-config`, `react-native-babel-preset`, `react-native-codegen`, and `react-native-babel-transformer`
- **Testing utilities** include `jest-preset`, `eslint-plugin-react-native`, and `eslint-config-react-native`
- **Development workflow** packages include `dev-middleware`, `debugger-shell`, `debugger-frontend`, and `community-cli-plugin`
- **Standalone utilities** like `virtualized-lists` can be consumed independently without the full framework

## Frequently Asked Questions

### Where is the main React Native source code located?

The main React Native source code is located in `packages/react-native/` within the monorepo. This directory contains the JavaScript bridge code in `Libraries/`, Android-specific native code in `ReactAndroid/`, and shared C++ code in `ReactCommon/` that powers both Android and iOS platforms.

### How does React Native organize its native code for Android and iOS?

React Native organizes native code using a split architecture where platform-specific code resides in separate directories while shared logic uses C++. Android code lives in `packages/react-native/ReactAndroid/` (Java and JNI bindings), while iOS code is in `packages/react-native/React/` and `packages/react-native/ReactCommon/` contains the shared C++ TurboModule and Fabric renderer implementations used by both platforms.

### Can I use React Native's list components without importing the entire framework?

Yes, you can use React Native's virtualization logic independently through the `virtualized-lists` package located at `packages/virtualized-lists/`. This standalone package exports `FlatList`, `SectionList`, and `VirtualizedList` implementations that can be consumed in web projects or other React environments without pulling in the native bridge dependencies required by the core `react-native` package.

### What is the purpose of react-native-codegen in the package structure?

`react-native-codegen` located in `packages/react-native-codegen/` is a build-time tool that generates typed native module bindings from JavaScript type definitions. It reads Flow or TypeScript interface definitions in the core package and automatically generates the C++ and platform-specific code needed for TurboModules and Fabric components, ensuring type safety between JavaScript and native code without manual boilerplate.