Public Wiki125,340View on GitHub
Want facebook/react-native knowledge in your AI?

Jest

This is the React Native open-source framework monorepo — the core platform that enables developers to build native iOS and Android mobile applications using React and JavaScript. It includes the full runtime (bridge, Fabric renderer, Turbo Modules), all built-in UI components, the animation system, the code generation pipeline (Flow/TypeScript to C++/ObjC/Java), the Android Gradle plugin, dev tooling (inspector proxy, debugger frontend, CLI commands), and the Yoga layout engine bindings.

Tech Stack

JestReactTypeScriptPostgreSQLNext.js

Key Features

  • Fabric Renderer & Turbo Modules
  • Built-in UI Components
  • Animated API
  • VirtualizedList / FlatList / SectionList
  • React Native Codegen
  • Dev Middleware & Inspector Proxy
  • Android Gradle Plugin
  • StyleSheet & Yoga Layout
  • Pressability System
  • W3C Web API Polyfills
  • Community CLI Plugin
  • LogBox

Entry Points

Start here when working with this codebase

React Native Main Index
packages/react-native/index.js

Root export file for the react-native package. All public APIs, components, and modules are re-exported from here.

Start here when adding a new public API, component, or module that needs to be accessible via `import { X } from 'react-native'`.

Dev Middleware Entry
packages/dev-middleware/src/createDevMiddleware.js

Creates the Express middleware stack for the dev server, including inspector proxy, debugger frontend serving, and open-debugger endpoint.

Start here when adding new dev server HTTP/WebSocket endpoints or modifying the debugging infrastructure.

Community CLI Plugin Entry
packages/community-cli-plugin/src/index.flow.js

Exports CLI commands (bundle, start) and their configurations for the React Native CLI.

Start here when adding new CLI commands or modifying the bundle/start command behavior.

Codegen Entry
packages/react-native-codegen/src/CodegenSchema.js

Defines the schema types used by the entire codegen pipeline for generating native code from JS specs.

Start here when modifying the codegen schema or adding new native module/component type support.

Virtualized Lists Entry
packages/virtualized-lists/index.js

Root export for the virtualized-lists package including VirtualizedList, FlatList, SectionList.

Start here when modifying list virtualization behavior, adding new list types, or changing viewability tracking.

Gradle Plugin Entry
packages/gradle-plugin/react-native-gradle-plugin/src/main/kotlin/com/facebook/react/ReactPlugin.kt

Main Gradle plugin class that registers all Android build tasks, codegen integration, and Hermes bundling.

Start here when modifying Android build behavior, adding new Gradle tasks, or changing autolinking.

Jest Configuration
jest.config.js

Central Jest configuration for the entire monorepo, defining transform rules, module mappings, and test setup.

Start here when adding new test file patterns, changing module resolution for tests, or modifying test transforms.

Jest Preprocessor
jest/preprocessor.js

Babel transform pipeline for Jest test execution, handling Flow stripping and module resolution.

Start here when tests fail due to transform issues or when adding support for new syntax in tests.

Private Feature Flags
packages/react-native/src/private/featureflags/ReactNativeFeatureFlags.js

Central feature flag definitions that gate new behavior across the React Native runtime.

Start here when adding a new feature flag to gate experimental functionality.

Android ReactAndroid Build
packages/react-native/ReactAndroid/build.gradle.kts

Main Gradle build file for the ReactAndroid native module, managing native compilation, dependencies, and publishing.

Start here when modifying Android native build configuration, adding native dependencies, or changing JNI compilation.

How to Make Changes

Common modification patterns for this codebase

Add a new built-in UI component (e.g., a new View-like component)

1
packages/react-native/Libraries/Components/

Create a new directory for your component (e.g., `MyComponent/`) with the main JS file. Define the component using `React.forwardRef` and call `codegenNativeComponent` to register it.

Pattern: Follow the pattern in packages/react-native/Libraries/Components/Switch/Switch.js which uses codegenNativeComponent for Fabric registration and defines props with Flow types.

2
packages/react-native/Libraries/Components/

Create a NativeComponent spec file (e.g., `MyComponentNativeComponent.js`) that defines the native props interface using codegen-compatible Flow types and exports via `codegenNativeComponent<NativeProps>('MyComponentName')`.

Pattern: Follow the pattern in packages/react-native/Libraries/Components/Switch/SwitchNativeComponent.js which exports typed native commands and component registration.

3
packages/react-native/index.js

Add a lazy getter export for the new component using `get MyComponent()` inside the module.exports block, requiring the component file lazily.

Pattern: Follow the pattern used for `Switch` in packages/react-native/index.js: `get Switch(): Switch { return require('./Libraries/Components/Switch/Switch').default; }`

4
packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/

Create the Android native ViewManager class that extends `SimpleViewManager<T>` or `BaseViewManager<T>`, implementing `createViewInstance`, `getName`, and `@ReactProp` setters.

Pattern: Follow the pattern in packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/switchview/ReactSwitchManager.java which registers props and creates the native view.

5
packages/react-native/Libraries/Components/__tests__/

Create a Jest test file (e.g., `MyComponent-test.js`) that tests rendering, prop handling, and event callbacks.

Pattern: Follow the pattern in packages/react-native/Libraries/Components/Switch/__tests__/Switch-test.js which uses `@testing-library/react-native` or `ReactTestRenderer` to verify component behavior.

Conventions to follow:

All component props must be defined with Flow types for codegen compatibilityUse `codegenNativeComponent<NativeProps>('ComponentName')` for Fabric-compatible registrationExport from packages/react-native/index.js using lazy `get` accessor pattern to avoid eager loadingNative commands (imperative methods) must use `codegenNativeCommands` from packages/react-native/Libraries/Utilities/codegenNativeCommands.jsAndroid ViewManagers must be registered in a ReactPackage implementation

Add a new Native Module (TurboModule)

1
packages/react-native/Libraries/

Create a new directory for your module (e.g., `MyModule/`). Create a `NativeMyModule.js` spec file that defines the module interface using `TurboModuleRegistry.getEnforcing<Spec>('MyModule')` with a Flow interface extending `TurboModule`.

Pattern: Follow the pattern in packages/react-native/Libraries/Vibration/NativeVibration.js which defines a `Spec` interface extending `TurboModule` with typed method signatures and exports via `TurboModuleRegistry.getEnforcing<Spec>('Vibration')`.

2
packages/react-native/Libraries/

Create the JS-facing module file (e.g., `MyModule.js`) that imports the native spec and wraps it with any JS-side logic.

Pattern: Follow the pattern in packages/react-native/Libraries/Vibration/Vibration.js which imports NativeVibration and provides a higher-level JS API.

3
packages/react-native/index.js

Add a lazy getter export for the new module in the module.exports block.

Pattern: Follow the pattern used for `Vibration` in packages/react-native/index.js: `get Vibration(): Vibration { return require('./Libraries/Vibration/Vibration'); }`

4
packages/react-native/ReactAndroid/src/main/java/com/facebook/react/modules/

Create the Android native module class extending `NativeMyModuleSpec` (codegen-generated base class) or `ReactContextBaseJavaModule`, annotating methods with `@ReactMethod`.

Pattern: Follow the pattern in packages/react-native/ReactAndroid/src/main/java/com/facebook/react/modules/vibration/VibrationModule.java which extends the codegen spec and implements the native methods.

5
packages/react-native/Libraries/__tests__/

Create a Jest test file that mocks the native module and tests the JS API.

Pattern: Follow the pattern in packages/react-native/Libraries/Vibration/__tests__/Vibration-test.js which uses `jest.mock` to mock the NativeModule and verifies method calls.

Conventions to follow:

Native module specs must use Flow interface extending TurboModule from packages/react-native/Libraries/TurboModule/RCTExport.jsUse `TurboModuleRegistry.getEnforcing<Spec>('ModuleName')` for required modules or `TurboModuleRegistry.get<Spec>('ModuleName')` for optional onesAll method parameter and return types must be codegen-compatible (primitives, Object, Array, Promise, etc.)Android modules must be registered in a ReactPackage's `getModule()` methodSpec file naming convention: `Native<ModuleName>.js`

Add a new dev server HTTP endpoint

1
packages/dev-middleware/src/createDevMiddleware.js

Register a new route handler in the middleware stack. Add a new `app.use()` or `app.get()`/`app.post()` call in the `createDevMiddleware` function, pointing to your new middleware handler.

Pattern: Follow the pattern of the `/open-debugger` endpoint registration in packages/dev-middleware/src/createDevMiddleware.js which delegates to a separate middleware module.

2
packages/dev-middleware/src/middleware/

Create a new middleware file (e.g., `myEndpointMiddleware.js`) that exports a connect-compatible middleware function `(req, res, next) => { ... }`.

Pattern: Follow the pattern in packages/dev-middleware/src/middleware/openDebuggerMiddleware.js which parses request parameters, performs logic, and sends JSON responses.

3
packages/dev-middleware/src/__tests__/

Create a test file for the new endpoint that starts a test server, makes HTTP requests, and asserts responses.

Pattern: Follow the pattern in packages/dev-middleware/src/__tests__/InspectorProxyHttpApi-test.js which uses `http.createServer`, connects the middleware, and uses `fetch` to test endpoints.

Conventions to follow:

Middleware functions use connect-style `(req, res, next)` signatureUse Flow types for all function parameters and return typesTest files use Jest and create isolated HTTP servers per test to avoid port conflictsError responses should use appropriate HTTP status codes and JSON error bodiesAll new files need the Meta copyright header comment

Add a new style property to the StyleSheet system

1
packages/react-native/Libraries/StyleSheet/StyleSheetTypes.js

Add the new style property to the appropriate Flow type definition (e.g., `ViewStyleProp`, `TextStyleProp`, `ImageStyleProp`, or the base `____LayoutStyle_Internal`).

Pattern: Follow how existing properties like `opacity` or `borderRadius` are defined in packages/react-native/Libraries/StyleSheet/StyleSheetTypes.js with their Flow type annotations.

2
packages/react-native/Libraries/StyleSheet/processStyles.js

If the new property requires special processing (e.g., color normalization, transform parsing), add processing logic here.

Pattern: Follow how color properties are processed in packages/react-native/Libraries/StyleSheet/processColor.js which normalizes color values before sending to native.

3
packages/react-native/Libraries/Components/View/ViewPropTypes.js

If the property is view-specific, ensure it's included in the view prop types.

Pattern: Follow how existing style-related props are typed in packages/react-native/Libraries/Components/View/ViewPropTypes.js.

4
packages/react-native/Libraries/StyleSheet/__tests__/

Add tests verifying the new property is accepted and processed correctly.

Pattern: Follow the test patterns in packages/react-native/Libraries/StyleSheet/__tests__/processStyles-test.js.

Conventions to follow:

Style property types must be defined in Flow in packages/react-native/Libraries/StyleSheet/StyleSheetTypes.jsColor values must go through processColor normalizationLayout properties that map to Yoga must be added to the ____LayoutStyle_Internal typeUse `?` prefix for optional properties in Flow types (e.g., `opacity?: number`)

Add a new Animated node type

1
packages/react-native/Libraries/Animated/nodes/

Create a new AnimatedNode subclass file (e.g., `AnimatedMyNode.js`) that extends `AnimatedNode` or `AnimatedWithChildren` and implements `__getValue()`, `__attach()`, `__detach()`, and `__getNativeConfig()`.

Pattern: Follow the pattern in packages/react-native/Libraries/Animated/nodes/AnimatedAddition.js which extends AnimatedWithChildren, implements value computation, and provides native config for offloading to the native animated driver.

2
packages/react-native/Libraries/Animated/Animated.js

Export the new node type or a factory function from the main Animated module.

Pattern: Follow how `Animated.add()` is exported in packages/react-native/Libraries/Animated/Animated.js as a static method that creates an AnimatedAddition instance.

3
packages/react-native/Libraries/Animated/NativeAnimatedHelper.js

If the node supports native animated driver, add the native node type constant and any required native API calls.

Pattern: Follow how existing native node types are registered in packages/react-native/Libraries/Animated/NativeAnimatedHelper.js.

4
packages/react-native/Libraries/Animated/__tests__/

Create tests for the new node type verifying value computation, attachment lifecycle, and native config generation.

Pattern: Follow the test patterns in packages/react-native/Libraries/Animated/__tests__/Animated-test.js which tests node creation, value updates, and listener callbacks.

Conventions to follow:

All animated nodes must extend AnimatedNode from packages/react-native/Libraries/Animated/nodes/AnimatedNode.jsNodes that have children must extend AnimatedWithChildrenNative animated config must return a plain object with `type` string matching the native implementationUse `__makeNative()` to signal the node should be offloaded to the native driverAll node files use Flow types and the `@flow strict-local` pragma

Add a new codegen type or modify schema

1
packages/react-native-codegen/src/CodegenSchema.js

Add or modify the type definition in the codegen schema. This is the central schema that all generators consume.

Pattern: Follow how existing types like `StringTypeAnnotation` or `ObjectTypeAnnotation` are defined as Flow type unions in packages/react-native-codegen/src/CodegenSchema.js.

2
packages/react-native-codegen/src/parsers/flow/

Update the Flow parser to recognize and parse the new type from Flow source files into the codegen schema representation.

Pattern: Follow the parsing logic in packages/react-native-codegen/src/parsers/flow/modules/index.js which maps Flow AST nodes to codegen schema types.

3
packages/react-native-codegen/src/parsers/typescript/

Update the TypeScript parser to handle the same new type from TS source files.

Pattern: Follow the parsing logic in packages/react-native-codegen/src/parsers/typescript/modules/index.js which mirrors the Flow parser but for TS AST.

4
packages/react-native-codegen/src/generators/

Update the native code generators (C++, ObjC, Java) to emit correct native code for the new type.

Pattern: Follow how existing types are handled in packages/react-native-codegen/src/generators/modules/GenerateModuleObjCpp/serializeMethod.js which maps schema types to ObjC++ type strings.

5
packages/react-native-codegen/src/__tests__/

Add test fixtures and snapshot tests for the new type across all parsers and generators.

Pattern: Follow the test fixture pattern in packages/react-native-codegen/src/parsers/flow/modules/__test_fixtures__/fixtures.js which defines module specs as string fixtures and verifies parsed output.

Conventions to follow:

Schema types in CodegenSchema.js must be exhaustive Flow union typesBoth Flow and TypeScript parsers must produce identical schema output for equivalent sourceGenerator tests use Jest snapshots to verify generated native codeTest fixtures are defined as string constants in dedicated __test_fixtures__ directoriesAll schema changes must be backward-compatible or versioned

Add a new feature flag

1
packages/react-native/src/private/featureflags/ReactNativeFeatureFlags.js

Add a new flag definition with a default value and a descriptive name. Export a getter function for the flag.

Pattern: Follow how existing flags are defined in packages/react-native/src/private/featureflags/ReactNativeFeatureFlags.js with a boolean default and a named export function.

2
packages/react-native/Libraries/

Import and use the feature flag in the relevant library code, gating the new behavior behind the flag check.

Pattern: Search for existing usages of `ReactNativeFeatureFlags` imports across packages/react-native/Libraries/ to see how flags gate behavior with simple if-checks.

Conventions to follow:

Feature flags default to `false` (disabled) for new experimental featuresFlag names should be descriptive and use camelCaseGate new behavior with `if (ReactNativeFeatureFlags.myFlag()) { ... }` patternFeature flags are the mechanism for gradual rollout; do not use environment variables

Coding Conventions

Standards and patterns used in this codebase

file-organization

Monorepo structure: apps/ contains deployable applications, packages/ contains shared libraries

Packages: packages/assets, packages/babel-plugin-codegen, packages/debugger-frontend
packages/assetspackages/babel-plugin-codegen
naming

File naming uses: kebab-case, PascalCase (for components/classes)

build.gradle.kts, jest.config.js, settings.gradle.kts, preprocessor.js, run-ci-javascript-tests.js
build.gradle.ktsjest.config.jssettings.gradle.kts
middleware

Middleware is used for cross-cutting concerns (auth, logging, validation)

Middleware files: packages/polyfills/error-guard.js
packages/polyfills/error-guard.js
configuration

Configuration is centralized in config files

Config files: jest.config.js, settings.gradle.kts
jest.config.jssettings.gradle.ktsprivate/helloworld/metro.config.js
module-exports

Use index.ts barrel files to export module public API

Each module has index.ts that re-exports public functions
private/eslint-plugin-monorepo/index.jsprivate/helloworld/index.jspackages/babel-plugin-codegen/index.js
typescript

Types are defined in dedicated type files

Type files: packages/react-native/ReactNativeApi.d.ts, packages/react-native-popup-menu-android/index.d.ts
packages/react-native/ReactNativeApi.d.tspackages/react-native-popup-menu-android/index.d.ts