Skip to content

AGENTS.md

Latest commit

 

History

History
109 lines (76 loc) · 4.29 KB

AGENTS.md

File metadata and controls

109 lines (76 loc) · 4.29 KB
Raw

react-native-screens

This project is a react-native library, focused on exposing native navigation containers and implementing common navigation paradigms such as stack, tabs, split.

Repository layout tips

  • ./src/ - JS side of the library

    • ./src/legacy/ - V4 implementation (legacy stack components, gesture-handler, reanimated integration, transition progress hooks, contexts). Re-exported from ./src/index.tsx for backward compatibility.

    • ./src/components/ - each directory inside contains JS code for new components, planned for next major release,

    • ./src/components/safe-area/ - code related to SafeAreaView component,

    • ./src/components/tabs/ - code related to TabsHost & TabsScreen components,

    • ./src/components/shared/ - shared types used across component families,

    • ./src/fabric/ - codegen specs for the components used by the native code generation tool

  • ./android/ - Android part of the library implementation,

  • ./ios/ - iOS part of the library implementation,

  • ./cpp/ and ./common/ - C++ layer, shared between Android and iOS parts. Legacy V4 shadow nodes, states, and descriptors live under legacy/ subdirectories (cpp/legacy/, common/cpp/.../rnscreens/legacy/).

  • ./FabricExample/ - contains an example application, we use it to showcase the library capabilities and test the library. It is not published as part of the package.

  • ./TVOSExample/ - tvOS example application, used to exercise the library on Apple TV. Like FabricExample, it consumes the shared sources from ./apps/ via path aliases. Not published as part of the package.

  • ./apps/ - extracted JS (react-native) code of the FabricExample application; this is done to share the code with other example applications in the repository.

  • ./react-navigation/ - this is a git submodule for a downstream library providing a complete navigation solution. It is not part of the library.

Build & run

Prerequisites

  • yarn install — installs JS dependencies. Triggers the prepare lifecycle hook, which builds the library to ./lib/ (see below).
  • yarn submodules — initializes and builds the react-navigation git submodule. Only needed when working against that downstream library; not required to build or type-check the screens library itself.

Build the library

yarn prepare

Runs bob build (react-native-builder-bob) and husky install. Outputs:

  • ./lib/commonjs/ — CommonJS build
  • ./lib/module/ — ES module build
  • ./lib/typescript/ — .d.ts declarations (built via tsconfig.build.json)

Source of truth is ./src/ (see react-native-builder-bob config in package.json).

Verify TypeScript

Library:

yarn check-types

Runs tsc --noEmit against the root tsconfig.json (covers ./src/).

Type-checking the example apps directly (FabricExample/, TVOSExample/, apps/) is intentionally not documented here yet. Each app's tsconfig.json currently surfaces a different set of pre-existing errors when run on its own, and there are no check-types scripts in the example app package.json files. This will be documented once the underlying issues are resolved and a single entry point exists.

Code conventions

  • TypeScript-first. Always prefer TypeScript over JavaScript unless explicitly working in a JS-only context.
  • PascalCase for component names, camelCase for hooks (e.g., useTabsNavigationContext).
  • Use context hooks when a context exists — do not pass context values as props.

Imports

  • Use relative imports within library packages (./src/).
  • Use path aliases (@apps/*, @assets/*) only in example apps (./apps/, ./FabricExample/, ./TVOSExample/).
  • Never use absolute paths from project root as import paths.

Git & refactoring

  • When renaming or deleting across the codebase, always grep for ALL references before committing. Verify zero stale references remain after the change.

Code review guidelines

Be extremely frank and focused on thoroughness.

Issue creation

If you intend to create an issue on this repository, adhere to templates from ./.github/ISSUE_TEMPLATE/! Issues that fail to conform will likely go stale or be closed without a response.

This applies in particular to bug reports without a reproducer. A reproducer is MANDATORY.