mirror of
https://github.com/facebook/react-native.git
synced 2026-11-18 20:19:07 +00:00
Update AGENTS.md (#58099)
Summary: Further updates to AGENTS.md, motivated by cloning this repo in additional environments (Cursor Cloud). **Changes** Restructure the guidance around what an agent needs to know before it starts, and correct several details against the repo. - Add an Environment section covering the package manager and which toolchain each surface needs. - Rescope Gotchas to the Yarn install and codegen build rough edges. - Correct the commands table: `yarn format-check` checks Prettier only, `yarn fantom` builds a native tester on first run, and JavaScript CI is the `lint`, `test_js`, and `build_js_types` jobs. - Separate RNTester into its own section. Changelog: [Internal] Pull Request resolved: https://github.com/react/react-native/pull/58099 Test Plan: — Reviewed By: christophpurrer Differential Revision: D117215889 Pulled By: Abbondanzo fbshipit-source-id: 29f83724bbf09540d16cc6fe6b904aa8d11f6e30
This commit is contained in:
1 parent
c35d3b4495
commit
f66a39d1cd
1 file changed
+30
-15
@@ -2,8 +2,6 @@
|
||||
|
||||
A framework for building native applications using React.
|
||||
|
||||
This file provides guidance for coding agents working in this repository.
|
||||
|
||||
## Repo structure
|
||||
|
||||
React Native is a monorepo: the `react-native` package, the packages published alongside it, and the apps and tooling used to develop them.
|
||||
@@ -22,32 +20,49 @@ React Native is a monorepo: the `react-native` package, the packages published a
|
||||
|
||||
Architecture 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.
|
||||
|
||||
## Common commands
|
||||
## Environment
|
||||
|
||||
Run these from the repository root:
|
||||
- Yarn v1, pinned via `packageManager`. Run commands from the repository root.
|
||||
- JavaScript work — lint, type checks, Jest, Metro — needs only Node and Yarn, on any platform.
|
||||
- Native builds need a platform toolchain: Xcode with CocoaPods or Swift Package Manager for iOS (macOS only), and the Android SDK and NDK with Gradle for Android. See [Building from source](https://reactnative.dev/contributing/how-to-build-from-source).
|
||||
|
||||
## Common commands
|
||||
|
||||
| Command | Purpose |
|
||||
| --- | --- |
|
||||
| `yarn test <path>` | Jest unit tests, found in `__tests__` directories |
|
||||
| `yarn fantom <path>` | [Fantom](private/react-native-fantom/__docs__/README.md) integration tests, named `*-itest.js` |
|
||||
| `yarn lint` | ESLint |
|
||||
| `yarn format` | Prettier and clang-format |
|
||||
| `yarn fantom <path>` | [Fantom](private/react-native-fantom/__docs__/README.md) integration tests, named `*-itest.js` — builds a native tester on first run |
|
||||
| `yarn lint` | ESLint (`--max-warnings 0`) |
|
||||
| `yarn flow-check` | Flow |
|
||||
| `yarn start`, `yarn android` | Metro, and RNTester on Android. See [RNTester](packages/rn-tester/README.md) for iOS |
|
||||
| `yarn format` | Prettier and clang-format (`yarn format-check` for Prettier only) |
|
||||
|
||||
Native 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).
|
||||
JavaScript CI is the `lint`, `test_js`, and `build_js_types` jobs in [`.github/workflows/test-all.yml`](.github/workflows/test-all.yml); Fantom and the native platforms have their own jobs.
|
||||
|
||||
### Verification: Running RNTester
|
||||
|
||||
Needed only for changes that have to be seen running, such as user interface behavior.
|
||||
|
||||
`yarn start` serves [RNTester](packages/rn-tester/README.md) over Metro at `http://localhost:8081`; `yarn android` builds and installs it on Android. Check the bundler with `curl "http://localhost:8081/js/RNTesterApp.bundle?platform=ios&dev=true"`.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- 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.
|
||||
- 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.
|
||||
- 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.
|
||||
- `CHANGELOG.md` is compiled at release time. Changelog entries belong in the pull request description.
|
||||
- `yarn install` dirties the working tree: a `preinstall` hook (`scripts/try-set-hermes-compiler-prebuilt.js`) resolves the `hermes-compiler` placeholder in `packages/react-native/package.json` (`0.0.0` → a real version) and touches `yarn.lock`. Expected — do not commit it.
|
||||
- Metro cannot bundle until codegen is built once — `yarn --cwd packages/react-native-codegen build`. Without it, bundling fails with `Cannot find module '@react-native/codegen/lib/parsers/flow/parser'`. Every other package runs from source — `yarn build` is not needed for development (see [`scripts/build/README.md`](scripts/build/README.md)).
|
||||
|
||||
## Generated code
|
||||
|
||||
Never hand-edit generated output — change the source and regenerate. CI validates the committed snapshots.
|
||||
|
||||
- Native modules and components are declared by JavaScript specs (`Native*.js`, `*NativeComponent.js`); their native counterparts are generated at build time.
|
||||
- Feature flags are declared in `packages/react-native/scripts/featureflags/ReactNativeFeatureFlags.config.js`; `yarn featureflags` regenerates the JavaScript, Java, and C++ accessors.
|
||||
- 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, then `yarn test-generated-typescript` to type-check the result.
|
||||
- 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`.
|
||||
- `CHANGELOG.md` is compiled at release time from pull request descriptions.
|
||||
|
||||
## Contributing guidelines
|
||||
|
||||
- Keep each change focused — no unrelated refactors, formatting, or dependency updates.
|
||||
- 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.
|
||||
- In the test plan, give the exact commands you ran and their results, plus screenshots or a video for user-interface changes.
|
||||
- In the test plan, give the exact commands you ran and their results, plus screenshots or a video for user-interface changes. Say which checks you could not run.
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full process, including how to report bugs.
|
||||
The full process is on [reactnative.dev](https://reactnative.dev/contributing/overview).
|
||||
Reference in new issue
Block a user