Skip to content

Commit 627c73a

Browse files
mikehardymikehardy
committed
docs: new architecture migration work queue
Add TurboModule migration OKF bundle with work queue, implementation workflow extending change authoring, and package-extensions cross-link.
1 parent 8867688 commit 627c73a

5 files changed

Lines changed: 373 additions & 0 deletions

File tree

‎okf-bundle/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ okf_version: "0.1"
2424

2525
* [Namespace API removal workflow](/namespace-api-removal-workflow.md) — modular-only migration checklist, factory design, removal greps
2626
* [Namespace API removal work queue](/namespace-api-removal-work-queue.md) — phase tracker and gate snapshots (ephemeral)
27+
* [TurboModule migration](/new-architecture/index.md) — Codegen TurboModules, coordinated New Architecture break, phase queue
2728

2829
# Packages
2930

‎okf-bundle/new-architecture/index.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# New Architecture (TurboModules)
2+
3+
TurboModule migration for React Native Firebase native bridge packages.
4+
5+
**Policy:** [OKF documentation and commit policy](../documentation-policy.md).
6+
7+
## Documents
8+
9+
* [Migration work queue](migration-work-queue.md) — ephemeral gates, phase ordering, package inventory
10+
* [TurboModule implementation workflow](turbomodule-implementation-workflow.md) — spec/codegen/native conversion, area harness; extends [change authoring](../testing/change-authoring-workflow.md)
11+
12+
## Reference implementation
13+
14+
* [`packages/functions`](../../../packages/functions/) — only package migrated to TurboModules today ([PR #8603](https://github.com/invertase/react-native-firebase/pull/8603); new-arch-only from v24)
15+
16+
## Related repository files
17+
18+
* [`packages/app/lib/internal/registry/nativeModule.ts`](../../../packages/app/lib/internal/registry/nativeModule.ts) — `turboModule` flag, null encoding, module wrapping
19+
* [`packages/app/lib/internal/nullSerialization.ts`](../../../packages/app/lib/internal/nullSerialization.ts) — iOS null sentinel for TurboModule object args
20+
* [`packages/functions/specs/NativeRNFBTurboFunctions.ts`](../../../packages/functions/specs/NativeRNFBTurboFunctions.ts) — Codegen spec pattern
21+
* [`packages/functions/package.json`](../../../packages/functions/package.json) — `codegenConfig`, committed generated output

‎okf-bundle/new-architecture/migration-work-queue.md‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
---
2+
type: Reference
3+
title: TurboModule migration work queue
4+
description: Phase tracker for migrating React Native Firebase packages from legacy NativeModules to Codegen TurboModules under a coordinated New Architecture break.
5+
tags: [new-architecture, turbomodule, codegen, migration, work-queue]
6+
timestamp: 2026-06-26T00:00:00Z
7+
---
8+
9+
# TurboModule migration — work queue
10+
11+
> **QUEUED (2026-06-26):** Planning document — awaiting maintainer review before implementation pickup.
12+
> **Goal/order:** app foundation → hard probe → easy wins → remaining complex → coordinated break → EventEmitter cleanup. Links: [implementation workflow](turbomodule-implementation-workflow.md), [change authoring](../testing/change-authoring-workflow.md), [functions reference](../../../packages/functions/) ([PR #8603](https://github.com/invertase/react-native-firebase/pull/8603)).
13+
14+
Ephemeral tracker; see [OKF policy](../documentation-policy.md).
15+
16+
---
17+
18+
## Locked decisions
19+
20+
| # | Decision | Detail |
21+
|---|----------|--------|
22+
| 1 | **New Architecture only** | One coordinated semver break across the monorepo. No dual old/new bridge support per package (`functions` precedent: v24). |
23+
| 2 | **Naming** | Codegen module names use `NativeRNFBTurbo*` prefix (e.g. `NativeRNFBTurboAuth`, `NativeRNFBTurboFirestore`). |
24+
| 3 | **Typing** | Strong Codegen types wherever the API allows. Source of truth: `packages/*/lib/types/internal.ts`, native method inventories, firebase-js-sdk shapes. Use `Object` / open maps only where payloads are genuinely dynamic. |
25+
| 4 | **Events** | **Defer** Codegen EventEmitter cutover to [Phase C cleanup](#deferred-cleanup-phase-eventemitter) unless testing proves deferral impossible. |
26+
| 5 | **Generated code** | Commit codegen output (`includesGeneratedCode: true`); mirror `packages/functions` layout. |
27+
| 6 | **Module resolution** | Unified resolver in `packages/app` — `TurboModuleRegistry.get(name)` with `NativeModules` fallback during transition. |
28+
29+
Implementation steps, harness, and commit rules: [turbomodule implementation workflow](turbomodule-implementation-workflow.md) — do not restate here.
30+
31+
---
32+
33+
## Resume checklist
34+
35+
Gate prerequisites before any `:test-cover` ([host rule](../testing/change-authoring-workflow.md#host-rule)):
36+
37+
1. [Pre-flight](../testing/running-e2e.md#pre-flight-is-the-host-clear-to-start): [host-clear probes](../testing/running-e2e.md#host-clear-probes), [services ready](../testing/running-e2e.md#2-services-ready), [harness matches validation tier](../testing/running-e2e.md#3-harness-matches-validation-tier) ([narrowing gate](../testing/running-e2e.md#harness-narrowing-gate-blocking) — required for **unit-focused** and **area-focused**; not [push harness](#harness)); [serial `:test-cover`](../testing/running-e2e.md#serialized-e2e-dispatch); [frozen tree](../testing/change-authoring-workflow.md#frozen-tree) for `independent-review`.
38+
2. New Architecture enabled on dev host / emulator for native bridge work.
39+
3. Per-package protocol: [Phase iteration protocol](#phase-iteration-protocol) below.
40+
41+
---
42+
43+
## What changes vs what stays
44+
45+
| Layer | Stays | Changes |
46+
|-------|-------|---------|
47+
| JS product API | `namespaced.ts`, `modular.ts`, web shims, `FirebaseModule` subclasses, arg prepending | `nativeModuleName` → `NativeRNFBTurbo*`; `turboModule: true` |
48+
| Events (Phases 0–5) | Compile-time event names, `SharedEventEmitter` fan-out, `nativeEvents` | Native emitters unchanged — see [Phase C](#deferred-cleanup-phase-eventemitter) |
49+
| Native | Firebase SDK integration, business logic | Extend generated `*Spec`; iOS `getTurboModule()`; podspec new-arch guard |
50+
| Release | Per-package semver today | **One coordinated major** when Phases 0–5 complete |
51+
52+
---
53+
54+
## Reference pattern (`functions`)
55+
56+
Brief index — full checklist: [turbomodule implementation workflow](turbomodule-implementation-workflow.md).
57+
58+
Each migrated package repeats the [`functions`](../../../packages/functions/) shape: `specs/NativeRNFBTurbo*.ts` → `codegenConfig` + committed generated output → Android `NativeRNFBTurbo*` / iOS spec + `getTurboModule()` → JS `turboModule: true`.
59+
60+
**Phase 0 still required:** unified module resolver; flip `getAppModule()` turbo TODO in [`nativeModule.ts`](../../../packages/app/lib/internal/registry/nativeModule.ts).
61+
62+
---
63+
64+
## Deferred cleanup phase (EventEmitter)
65+
66+
Follow-on **after** Phases 0–5 and coordinated break. Not in scope unless testing blocks deferral.
67+
68+
| Topic | Current | Cleanup target |
69+
|-------|---------|----------------|
70+
| Event subscription | `RNFBNativeEventEmitter` + `RNFBAppModule` proxy | Codegen TurboModule events or RN New Architecture event emitters |
71+
| Native emit | `RNFBRCTEventEmitter` / `ReactNativeFirebaseEventEmitter` | Align with chosen Codegen event pattern |
72+
| JS fan-out | Fixed `nativeEvents` + `SharedEventEmitter` prefixes | Re-evaluate once native side supports typed events |
73+
74+
**Deferral discriminator:** if **area-focused** e2e or device testing shows TurboModule migration **cannot** work with the legacy event proxy, escalate that package's event path into the active migration PR — do not wait for Phase C.
75+
76+
---
77+
78+
## Package inventory
79+
80+
### No native bridge (out of scope)
81+
82+
| Package | Notes |
83+
|---------|-------|
84+
| `@react-native-firebase/ai` | Pure JS |
85+
| `@react-native-firebase/vertexai` | Re-export over `ai` |
86+
87+
### Already migrated
88+
89+
| Package | TurboModule(s) | Status |
90+
|---------|----------------|--------|
91+
| `@react-native-firebase/functions` | `NativeRNFBTurboFunctions` | ✅ reference |
92+
93+
### Native packages — complexity summary
94+
95+
Android `@ReactMethod` counts approximate spec surface area. Multi-module: **one spec per legacy module** ([workflow § multi-module](turbomodule-implementation-workflow.md#multi-module-packages)).
96+
97+
#### Multi-module (Tier A)
98+
99+
| Package | Legacy modules | Events | Methods ≈ | Notes |
100+
|---------|----------------|--------|-----------|-------|
101+
| **database** | 5 modules (`RNFBDatabase*`) | 2 | ~22 | Transaction + sync listeners |
102+
| **firestore** | 4 modules (`RNFBFirestore*`) | 4 | ~31 | Pipelines via `pipelineExecute`; listener IDs |
103+
104+
#### Single-module, high complexity (Tier B)
105+
106+
| Package | Legacy module | Events | Methods ≈ | Notes |
107+
|---------|---------------|--------|-----------|-------|
108+
| **auth** | `RNFBAuthModule` | 3 | **59** | Largest single spec |
109+
| **messaging** | `RNFBMessagingModule` | 5–7 | 11 | Platform-conditional events; background iOS |
110+
111+
#### Single-module, moderate (Tier C)
112+
113+
| Package | Legacy module | Events | Methods ≈ |
114+
|---------|---------------|--------|-----------|
115+
| **storage** | `RNFBStorageModule` | 1 | 14 |
116+
| **crashlytics** | `RNFBCrashlyticsModule` | 0 | 14 |
117+
| **analytics** | `RNFBAnalyticsModule` | 0 | 11 |
118+
| **remote-config** | `RNFBConfigModule` | 1 | 11 |
119+
| **app-check** | `RNFBAppCheckModule` | 1 | 7 |
120+
| **perf** | `RNFBPerfModule` | 0 | 7 |
121+
122+
#### Single-module, simple (Tier D)
123+
124+
| Package | Legacy module | Events | Methods ≈ | Notes |
125+
|---------|---------------|--------|-----------|-------|
126+
| **installations** | `RNFBInstallationsModule` | 0 | 3 | Smallest |
127+
| **in-app-messaging** | `RNFBFiamModule` | 0 | 3 | |
128+
| **app-distribution** | `RNFBAppDistributionModule` | 0 | 4 | |
129+
| **ml** | `RNFBMLModule` | 0 | ~0 | Stub |
130+
| **phone-number-verification** | `RNFBPnvModule` | 0 | 6 | Android-only; direct resolver |
131+
132+
#### Foundation (Phase 0)
133+
134+
| Package | Legacy modules | Notes |
135+
|---------|----------------|-------|
136+
| **app** | `RNFBAppModule`, `RNFBUtilsModule` (+ Android utils) | Event proxy; **blocker** for migration complete |
137+
138+
---
139+
140+
## Phase ordering
141+
142+
Strategy: **foundation → hard probe → easy wins → remaining complex → coordinated break → cleanup**.
143+
144+
Pick **one** of `firestore` or `auth` in Phase 1 (firestore = multi-module + pipelines; auth = max single-module spec).
145+
146+
### Phase table
147+
148+
| Phase | Focus | Status | Packages |
149+
|-------|--------|--------|----------|
150+
| **0** | App foundation + unified resolver | queued | `app` |
151+
| **1** | Hard probe | queued | `firestore` **or** `auth` — pick one |
152+
| **2** | Easy wins | queued | `installations`, `perf`, `in-app-messaging`, `app-distribution`, `ml` |
153+
| **3** | Moderate | queued | `app-check`, `remote-config`, `analytics`, `crashlytics`, `storage` |
154+
| **4** | Remaining complex | queued | other Tier A/B + `messaging`, `database` |
155+
| **5** | Android-only / misc | queued | `phone-number-verification` |
156+
| **R** | Pre-merge full validation | queued | Revert harness narrowing; [full tier](../testing/running-e2e.md#e2e-validation-tiers-unit-focused-area-focused-full) 3-platform before coordinated major |
157+
| **C** | EventEmitter cleanup | deferred | All — [§ deferred cleanup](#deferred-cleanup-phase-eventemitter) |
158+
159+
**Coordinated break:** consumer-facing major when Phases 0–5 + **R** complete (`functions` already new-arch-only).
160+
161+
---
162+
163+
## Phase iteration protocol
164+
165+
Each package (or one legacy module within a multi-module package) follows **one** serial loop. No overlap. Work types: [change authoring workflow § work types](../testing/change-authoring-workflow.md#work-types).
166+
167+
| Step | Work type | Closes gate | Rules |
168+
|------|-----------|-------------|-------|
169+
| **1** | `gap-analysis` | — | Spec inventory + feasibility; read-only when export shape unclear |
170+
| **2** | `baseline-capture` | — | Optional area-focused e2e baseline before large packages |
171+
| **3** | `implementation` | `implementation` | Spec, codegen, native, JS; Jest + **unit-focused** tier; `.only` / area narrowing OK locally; **no commit** |
172+
| **4** | `independent-review` | `review` | **Frozen tree**; **area-focused** tier; no `.only`; [area harness](turbomodule-implementation-workflow.md#turbomodule-area-harness); serial [host rule](../testing/change-authoring-workflow.md#host-rule) |
173+
| **5** | `documentation` | — | User docs + durable OKF when applicable |
174+
| **6** | `commit` | `commit` | One focused commit only after `review_gate` closed |
175+
176+
Canonical commands: [validation checklist](../testing/validation-checklist.md), [serialized dispatch](../testing/running-e2e.md#serialized-e2e-dispatch).
177+
178+
Skip steps 1–2 when spec shape is known (most Tier D packages).
179+
180+
---
181+
182+
## Current snapshot
183+
184+
**Label:** `planning`; **harness:** not started
185+
186+
**Next item:** Maintainer review of this queue + [implementation workflow](turbomodule-implementation-workflow.md) → Phase **0** pickup.
187+
188+
**Arbiter gate:**
189+
190+
191+
| Item | Code | `implementation_gate` | `review_gate` | `next_work_type` | `validation_tier` | Notes |
192+
|------|------|----------------------|---------------|------------------|-------------------|-------|
193+
| Phase 0 `app` | — | — | — | — | — | blocked on queue approval |
194+
195+
---
196+
197+
## Harness
198+
199+
- **Push state (committed):** full test app — all `platformSupportedModules` + `require.context` in `tests/app.js`. For CI / Phase **R** only.
200+
- **Local `:test-cover`:** must match arbiter `validation_tier` — [running e2e § harness + narrowing gate](../testing/running-e2e.md#harness-narrowing-gate-blocking). **`implementation` → unit-focused** and **`independent-review` → area-focused:** both require [area narrowing](turbomodule-implementation-workflow.md#turbomodule-area-harness) locally **before** first run even when git has full harness. Revert before **R** (full tier).
201+
202+
---
203+
204+
## Workflow (each phase)
205+
206+
1. Pick package(s) for the phase from [phase table](#phase-table).
207+
2. Follow [Phase iteration protocol](#phase-iteration-protocol) — never commit before `review_gate` closed; never overlap `:test-cover` ([host rule](../testing/change-authoring-workflow.md#host-rule)).
208+
3. Update arbiter gate row when item closes.
209+
4. Phase **R:** `pre-merge-validation` at **full** tier before coordinated major.
210+
211+
**Pitfalls:** iOS null-in-object on option maps ([workflow § gotchas](turbomodule-implementation-workflow.md#gotchas)); New Architecture must be enabled; do not combine language modernization (Kotlin/Swift) with bridge migration in the same PR.
212+
213+
---
214+
215+
## Related links
216+
217+
* [New Architecture index](index.md)
218+
* [TurboModule implementation workflow](turbomodule-implementation-workflow.md)
219+
* [Change authoring workflow](../testing/change-authoring-workflow.md)
220+
* [Documentation policy](../documentation-policy.md)

0 commit comments

Comments
 (0)