AGENTS.md

1# React Native
2 
3A framework for building native applications using React.
4 
5This file provides guidance for coding agents working in this repository.
6 
7## Repo structure
8 
9React Native is a monorepo: the `react-native` package, the packages published alongside it, and the apps and tooling used to develop them.
10 
11| Path | Contents |
12| --- | --- |
13| `packages/react-native/Libraries` | JavaScript source (Flow) — the legacy location, with code gradually moving to `src/private` |
14| `packages/react-native/src/private` | JavaScript source (Flow) |
15| `packages/react-native/ReactCommon` | Shared C++ — Fabric renderer, TurboModules, JSI, Yoga, `jsinspector-modern` |
16| `packages/react-native/ReactAndroid` | Android runtime (Kotlin, Java, JNI) |
17| `packages/react-native/{React,ReactApple}` | Apple runtime (Objective-C++, Swift) |
18| `packages/rn-tester` | RNTester — test app showcasing each core component and API, plus a `Playground` scratch surface |
19| `packages/*` | Other published packages — Metro config, Codegen, ESLint config, dev-middleware, React Native DevTools frontend |
20| `private/*` | Unpublished — the `helloworld` sample app, the `react-native-fantom` test runner |
21| `scripts/*` | Repository tooling — build, test, release, and CI scripts |
22 
23Architecture notes live in `__docs__` directories beside the code they describe, indexed by [`__docs__/README.md`](__docs__/README.md). Treat them as reference for the subsystem you are working in, not as required reading.
24 
25## Common commands
26 
27Run these from the repository root:
28 
29| Command | Purpose |
30| --- | --- |
31| `yarn test <path>` | Jest unit tests, found in `__tests__` directories |
32| `yarn fantom <path>` | [Fantom](private/react-native-fantom/__docs__/README.md) integration tests, named `*-itest.js` |
33| `yarn lint` | ESLint |
34| `yarn format` | Prettier and clang-format |
35| `yarn flow-check` | Flow |
36| `yarn start`, `yarn android` | Metro, and RNTester on Android. See [RNTester](packages/rn-tester/README.md) for iOS |
37 
38Native builds use Gradle on Android, and CocoaPods or Swift Package Manager on iOS. See [Building from source](https://reactnative.dev/contributing/how-to-build-from-source).
39 
40## Gotchas
41 
42- JavaScript sources are typed with Flow, and the public API is exported from `packages/react-native/index.js`. TypeScript types are generated from those sources, and `packages/react-native/ReactNativeApi.d.ts` is a committed snapshot of that API — run `yarn build-types` to regenerate both whenever the public API changes.
43- The public native API is snapshotted as well: C++ under `scripts/cxx-api` (`yarn cxx-api-build`), and Android in `packages/react-native/ReactAndroid/api/ReactAndroid.api`. CI validates both.
44- Native modules and components are declared by JavaScript specs (`Native*.js`, `*NativeComponent.js`), from which their native counterparts are generated. Do not hand-edit generated code.
45- `CHANGELOG.md` is compiled at release time. Changelog entries belong in the pull request description.
46 
47## Contributing guidelines
48 
49- Keep each change focused — no unrelated refactors, formatting, or dependency updates.
50- Complete the pull request template — the motivation and the user-visible effect, and a [changelog entry](https://reactnative.dev/contributing/changelogs-in-pull-requests) with its category and type tags.
51- In the test plan, give the exact commands you ran and their results, plus screenshots or a video for user-interface changes.
52 
53See [CONTRIBUTING.md](CONTRIBUTING.md) for the full process, including how to report bugs.
54