mirror of https://github.com/react/react-native.git synced 2026-09-28 21:33:11 +08:00

Files

T

History

Christian Falch a6898cc4cf docs(swiftpm): rename __doc__ to __docs__, drop two superseded docs, correct the rest (#58006 )

Summary:
Rebased onto `main` after https://github.com/react/react-native/issues/57757, https://github.com/react/react-native/issues/57756, https://github.com/react/react-native/issues/57762 and https://github.com/react/react-native/issues/57744 landed. Because this
PR renames `__doc__` and Prettier-formats every file, a hunk-level rebase was the
wrong tool — it stopped on the second of nine commits and the reformat commit then
conflicted with everything after it. So the history is **replayed** on top of the
new `main` instead, and reordered to put Prettier *before* the content edits, which
makes the substantive diff reviewable rather than tangled with reflow.

Verified nothing those four PRs added was lost: every heading on `main` survives
except the two this PR deliberately renames, and their facts — the
`artifactsVersionOverride` pin, the autolinking-config-command pin, the
pre-injection build-setting values, and the promoted-scalar caveat — are carried
into the new "Files the tool touches" table rather than sitting in a row this PR
deletes.

Housekeeping and accuracy pass over `packages/react-native/scripts/spm/__docs__`.
Docs only — no code or test changes.

**Rename.** `scripts/spm/__doc__` was the only `__doc__` directory in the repo;
every other subsystem uses `__docs__` (27+ directories, and the convention
documented in `__docs__/GUIDELINES.md`). The misspelling also meant these files
were **published to npm**: `package.json` includes `scripts/spm` in `files` and
excludes `!**/__docs__/**`, which the misspelled directory dodged.

**Removed two superseded documents.** `rfc-spm-xcframework.md` (707 lines) was a
stale ancestor of RFC0994, still describing `spm init`, xcodeproj *generation*, the
`.xcodeproj.legacy` rename migration, a `spm clean` command that does not exist,
stub `Package.swift` files and VFS overlays. `spm-plugins-assessment.md` evaluated
SwiftPM plugins as a replacement for the injected build phases — conclusion valid,
detail stale (it listed a "Prepare VFS Overlay" phase). Both have had their durable
content folded into RFC0994.

**Corrected the remaining docs against the implementation.** The substantive one:
auto-sync is **two** hooks, not one — a scheme pre-action in the app's *shared*
scheme plus the build phase. The docs described only the phase.

Two claims here are corrections of my own earlier drafts, made after testing them
on `private/helloworld` rather than reading the code:

- Neither hook can bootstrap a clean checkout. With `build/` deleted,
`xcodebuild -scheme … build` fails in nine lines of log, `Resolve Package Graph`
first, the pre-action never running. The one-time setup run really is required,
and the ordering table now shows the measured sequence.
- A sync failure is not unconditionally non-fatal. Exit 2 — a dependency with no
`Package.swift` — maps to `exit 1` and fails the build deliberately; only other
non-zero codes warn. As written, the doc also contradicted the exit-2 behaviour
documented elsewhere in the same file.

Smaller fixes: `hermesvm` → `hermes-engine` (that name is in no code), plugin
`watchPaths` added to the staleness inputs, and the `#auto-sync-build-phase`
anchors left dangling by the heading rename.

**Added a `__docs__/README.md` index**, per `GUIDELINES.md`, plus a **"Files the
tool touches"** table — there was no single answer to what the tool creates or
modifies. Writing it surfaced that `add` creates or appends to `ios/.gitignore`
(documented nowhere), and that `deinit` does not revert that block, anything
`--deintegrate` changed, or a promoted array setting — so the "exact inverse of
`add`" claim needed qualifying in three places.

**Documented `spm.dependencies`**, the SwiftPM analog of a podspec's
`s.dependency`, which was implemented but absent from every doc, and corrected the
scaffold prerequisite: it is `add`/`update` that stops, with a distinct exit code 2,
not the build.

**Prettier-formatted the docs, in its own commit.** These were the only unformatted
markdown files in the repository, so `prettier --list-different "./**/*.md"` goes
from three failures to clean.

## Changelog:

[Internal] - SwiftPM docs: rename `__doc__` to `__docs__`, remove two superseded
documents, and correct the rest against the implementation

Pull Request resolved: https://github.com/react/react-native/pull/58006

Test Plan:
- `npx prettier --check "packages/react-native/scripts/spm/__docs__/*.md"` passes;
`npx prettier --list-different "./**/*.md"` is empty for the whole repo.
- All 19 intra-doc anchor links verified against GitHub's slug rules; none dead.
Every relative path out of the new README resolves, including the root-index hop.
- `npm pack --dry-run --ignore-scripts` lists no `scripts/spm/__docs__/` entries
while every `scripts/spm/*.js` still ships.
- The Prettier commit is content-neutral: comparing `[A-Za-z0-9]+` token streams
across it, all three files are identical word for word.
- Behavioural claims traced to source: `VALID_ACTIONS` in `setup-apple-spm.js`;
`injectOrCreateScheme` / `addPreActionToScheme` and the `RC -eq 2` branch of
`buildSyncAutolinkingScript` in `generate-spm-xcodeproj.js`; `BUILTIN_FRAMEWORKS`
in `flavored-frameworks.js`; `generateXCFrameworksPackageSwift` in
`generate-spm-package.js`; `ensureGitignoreSpmEntries` and its `action =--sanitized--

Reviewed By: fabriziocucci

Differential Revision: D116598871

Pulled By: cipolleschi

fbshipit-source-id: b1822dcc885b9c882ec3a2626addc42553244b51

2026-08-19 09:19:58 -07:00

GUIDELINES.md

Prettify markdown files in __docs__ (#50587 )

2025-04-09 05:42:48 -07:00

README-template.md

Use emojis in technical docs titles (#50699 )

2025-04-14 05:41:02 -07:00

README.md

docs(swiftpm): rename __doc__ to __docs__, drop two superseded docs, correct the rest (#58006 )

2026-08-19 09:19:58 -07:00

README.md

React Native Technical Documentation

The React Native technical documentation describes how React Native works internally, the subsystems it is composed of, how they work and how they interact with each other.

The intended audience is people who want to learn about the internals of React Native and contribute to it. End users of React Native are meant to use the public website instead (its code can be found here).

For details on how we approach technical documentation in this repository, see GUIDELINES.md.

🚀 Usage

This repository is not meant to be consumed directly by end users. Instead, it creates several packages that are published to the NPM registry for direct consumption by end users and frameworks.

This repository uses a monorepo approach, and public packages can be found in the packages directory (the ones that do not contain "private": true in their package.json file).

The most important package is the react-native package, located in packages/react-native, which contains the public JavaScript API.

This repository provides the Android and iOS versions of React Native. Versions for other platforms are maintained in their own repositories.

📐 Design

TODO: Explain the different components of React Native at a high level.

🔗 Relationship with other systems

Part of this

Runtime
- Cross-platform
  - Feature Flags
  - Host / Instance / Bridgeless
  - UI / Fabric
    - Events
    - Shadow Tree Lifecycle
      - Runtime Shadow Node Reference Update
      - passChildrenWhenCloningPersistedNodes
    - Layout
    - Mounting
    - Animation Backend
  - Native Modules / TurboModules
  - JS Runtime
    - Event Loop
    - Globals and environment setup
    - Error handling
  - Developer Tools
    - React Native DevTools
      - Infrastructure
        
        Inspector proxy protocol
    - LogBox
  - Misc
    - Web APIs
      - DOM Traversal & Layout APIs
      - IntersectionObserver
      - MutationObserver
      - Performance & PerformanceObserver
      - Timers
- Platform-specific
  - Host Platform Interface
- Android
  - UI
    - Events
    - Mounting
- iOS
  - UI
    - Events
    - Mounting
Build system
- Android
- iOS
  - SwiftPM
- C++
- JavaScript
  - Metro
Testing
- Android
- iOS
- C++
- JavaScript
  - Flow
  - TypeScript
  - Jest
  - ESLint
- Integration / E2E
  - Fantom

Used by this

This repository has many different types of dependencies: build systems, external packages to be used during development, external packages used at runtime, etc.

Uses this

The main use cases for this repository are:

Developing React Native itself.
Testing and releasing React Native.
Synchronizing forks like react-native-windows and react-native-macos.