refactor(perf): return sync parity for metric controls

Author: mikehardy

.github/scripts/compare-types/configs/perf-config.ts

@@ -62,9 +62,9 @@ const config: PackageConfig = {
     {
       name: 'PerformanceTrace',
       reason:
-        'React Native uses async `start`/`stop` (`Promise<null>`) because work crosses the native bridge. ' +
-        'The web SDK uses synchronous `start`/`stop` and exposes `record()`. RN Firebase exposes ' +
-        '`getMetrics` and `removeMetric` for native-backed custom metrics instead of the web shape.',
+        'React Native uses synchronous `start`/`stop` (in-memory native calls via TurboModules), matching ' +
+        'the firebase-js-sdk web `start`/`stop`. The web SDK additionally exposes `record()`, while RN Firebase ' +
+        'exposes `getMetrics` and `removeMetric` for native-backed custom metrics instead.',
     },
   ],
 };

docs/migrating-to-v26.mdx

@@ -90,7 +90,7 @@ When migrating from firebase-js-sdk web examples, watch for these high-impact ru
 | **Cloud Storage**             | `uploadBytes` / `uploadString` from JS blobs                                                                                                 | `putFile` and `writeToFile` are **native-only** file-path APIs with no firebase-js-sdk equivalent. Retry-time setters are modular functions on RN, not instance properties.                                                                                                                |
 | **Cloud Messaging**           | Web push / service-worker surface                                                                                                            | FCM token lifecycle, permissions, background handlers, and **APNs token APIs are iOS only**. Event delivery still uses the legacy native event proxy during the TurboModule migration; behavior matches pre-v26 releases but will change when Codegen events land in a future release.     |
 | **Remote Config**             | `reset()` clears server and local state                                                                                                      | `reset()` is **Android only** — iOS does not clear activated, fetched, or default Remote Config values. `setDefaultsFromResource` loads from native resource files (`.plist` / XML).                                                                                                       |
-| **Performance**               | `initializePerformance` returns synchronously; trace `start`/`stop` are sync                                                                 | `initializePerformance` is **synchronous** on RN (applies settings to the native instance). Trace `start`/`stop` are **async** through the native bridge.                                                                                                                                  |
+| **Performance**               | `initializePerformance` returns synchronously; trace `start`/`stop` are sync                                                                 | `initializePerformance` is **synchronous** on RN (applies settings to the native instance). Trace, HTTP metric, and screen trace `start`/`stop` are **synchronous** through TurboModules, matching firebase-js-sdk.                                                                                                                                  |
 | **Firestore**                 | IndexedDB persistence, `memoryLocalCache`, `persistentLocalCache`                                                                            | Local cache factories and IndexedDB APIs are **web only**. Persistence is controlled by the native Firestore SDK. `initializeFirestore` is **async** on RN.                                                                                                                                |
 | **App Check**                 | reCAPTCHA version 3 / Enterprise web providers                                                                                               | Use `ReactNativeFirebaseAppCheckProvider` for Device Check, App Attest, Play Integrity, etc. Web reCAPTCHA provider classes have **no RN equivalent**.                                                                                                                                     |
 | **RN-native-only modules**    | No web SDK                                                                                                                                   | `crashlytics`, `in-app-messaging`, `app-distribution`, and `ml` are **React Native only** — no firebase-js-sdk modular surface.                                                                                                                                                            |
@@ -402,6 +402,11 @@ The namespaced API for `@react-native-firebase/perf` has been **removed**. This
 | `perf().newTrace()`        | `trace(performance, name)`                                               |
 | `perf().newHttpMetric()`   | `httpMetric(performance, url, httpMethod)`                               |
 
+## Signature changes
+
+- `Trace`, `HttpMetric`, and `ScreenTrace` `start()` / `stop()` now return `void` synchronously (previously `Promise<null>`), matching the firebase-js-sdk web `PerformanceTrace`. The underlying native calls are in-memory, so no `await` is required — remove any `await` on these calls.
+- `startScreenTrace(performance, screenName)` and the internal `startTrace(name)` helper now return the trace instance synchronously instead of a `Promise`.
+
 # App Check
 
 The namespaced API for `@react-native-firebase/app-check` has been **removed**. This package is **modular-only** — use `getAppCheck()` / `initializeAppCheck()` and root-level helper functions.

docs/perf/axios-integration.mdx

@@ -32,7 +32,7 @@ axios.interceptors.request.use(async function (config) {
     // add any extra metric attributes, if required
     // httpMetricInstance.putAttribute('userId', '12345678');
 
-    await httpMetricInstance.start();
+    httpMetricInstance.start();
   } finally {
     return config;
   }
@@ -62,7 +62,7 @@ axios.interceptors.response.use(
 
       httpMetric.setHttpResponseCode(response.status);
       httpMetric.setResponseContentType(response.headers['content-type']);
-      await httpMetric.stop();
+      httpMetric.stop();
     } finally {
       return response;
     }
@@ -78,7 +78,7 @@ axios.interceptors.response.use(
 
       httpMetric.setHttpResponseCode(error.response.status);
       httpMetric.setResponseContentType(error.response.headers['content-type']);
-      await httpMetric.stop();
+      httpMetric.stop();
     } finally {
       // Ensure failed requests throw after interception
       return Promise.reject(error);

docs/perf/ky-integration.mdx

@@ -38,7 +38,7 @@ const api = ky.create({
         // options.metric.putAttribute('userId', '12345678');
         // options.metric.setRequestPayloadSize(1234)
 
-        await options.metric.start();
+        options.metric.start();
       },
     ],
   },
@@ -73,7 +73,7 @@ const api = ky.create({
         metric.setHttpResponseCode(status);
         metric.setResponseContentType(getHeader('Content-Type', headers));
         metric.setResponsePayloadSize(getContentLength(headers));
-        await metric.stop();
+        metric.stop();
       },
     ],
   },
@@ -113,7 +113,7 @@ const api = ky.create({
         // options.metric.putAttribute('userId', '12345678');
         // options.metric.setRequestPayloadSize(1234)
 
-        await options.metric.start();
+        options.metric.start();
       },
     ],
 
@@ -124,7 +124,7 @@ const api = ky.create({
         metric.setHttpResponseCode(status);
         metric.setResponseContentType(getHeader('Content-Type', headers));
         metric.setResponsePayloadSize(getContentLength(headers));
-        await metric.stop();
+        metric.stop();
       },
     ],
   },

docs/perf/usage/index.mdx

@@ -55,7 +55,7 @@ apply plugin: 'com.google.firebase.firebase-perf'
 | **Platforms**        | Android, iOS (native Firebase SDK)                                                             |
 | **New Architecture** | **Required** from v26. See [Migrating to v26](/migrating-to-v26#new-architecture-requirement). |
 
-**Platform notes:** `initializePerformance` returns synchronously on RN. Custom trace `start`/`stop` are async through the native bridge (unlike the web SDK).
+**Platform notes:** `initializePerformance` returns synchronously on RN. Trace, HTTP metric, and screen trace `start`/`stop` are synchronous through TurboModules, matching firebase-js-sdk.
 
 # What does it do
 
@@ -81,14 +81,14 @@ Below is how you would measure the amount of time it would take to complete a sp
 ```jsx
 import { getPerformance, trace } from '@react-native-firebase/perf';
 
-async function customTrace() {
+function customTrace() {
   const perf = getPerformance();
   const t = trace(perf, 'custom_trace');
 
-  await t.start();
+  t.start();
   t.putAttribute('user', 'abcd');
   t.putMetric('credits', 30);
-  await t.stop();
+  t.stop();
 }
 ```
 
@@ -99,10 +99,10 @@ Record a custom screen rendering trace (slow frames / frozen frames)
 ```jsx
 import { getPerformance, startScreenTrace } from '@react-native-firebase/perf';
 
-async function screenTrace() {
+function screenTrace() {
   try {
-    const screenTrace = await startScreenTrace(getPerformance(), 'FooScreen');
-    await screenTrace.stop();
+    const screenTrace = startScreenTrace(getPerformance(), 'FooScreen');
+    screenTrace.stop();
   } catch (e) {
     // rejects if iOS or (Android == 8 || Android == 8.1)
     // or if hardware acceleration is off
@@ -122,14 +122,14 @@ async function getRequest(url) {
 
   metric.putAttribute('user', 'abcd');
 
-  await metric.start();
+  metric.start();
 
   const response = await fetch(url);
   metric.setHttpResponseCode(response.status);
   metric.setResponseContentType(response.headers.get('Content-Type'));
   metric.setResponsePayloadSize(response.headers.get('Content-Length'));
 
-  await metric.stop();
+  metric.stop();
 
   return response.json();
 }

jest.setup.ts

@@ -435,12 +435,12 @@ jest.doMock('react-native', () => {
           isInstrumentationEnabled: true,
           instrumentationEnabled: jest.fn(() => Promise.resolve()),
           setPerformanceCollectionEnabled: jest.fn(() => Promise.resolve()),
-          startScreenTrace: jest.fn(() => Promise.resolve()),
-          stopScreenTrace: jest.fn(() => Promise.resolve()),
-          startTrace: jest.fn(() => Promise.resolve()),
-          stopTrace: jest.fn(() => Promise.resolve()),
-          startHttpMetric: jest.fn(() => Promise.resolve()),
-          stopHttpMetric: jest.fn(() => Promise.resolve()),
+          startScreenTrace: jest.fn(),
+          stopScreenTrace: jest.fn(),
+          startTrace: jest.fn(),
+          stopTrace: jest.fn(),
+          startHttpMetric: jest.fn(),
+          stopHttpMetric: jest.fn(),
         },
         NativeRNFBTurboPnv: {
           enableTestSession: jest.fn(() => Promise.resolve()),

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

@@ -332,9 +332,9 @@ Skip steps 1–2 when spec shape is known (most Tier D packages).
 
 **Label:** `phase-s-sync-conversion` (2026-07-03)
 
-**Next item:** Phase **S** perf metric controls sync conversion (`PS-perf-metrics`)
+**Next item:** Phase **S** database sync controls (`PS-database-online` — after perf commit)
 
-**Current gates:** PS-auth-parsers all gates **closed** — committing `refactor(auth): return sync parity for auth parsers`.
+**Current gates:** PS-perf-metrics all gates **closed** — committing `refactor(perf): return sync parity for metric controls`.
 
 **Host rule:** one `:test-cover` at a time — never parallel subagents with e2e.
 
@@ -373,7 +373,8 @@ Skip steps 1–2 when spec shape is known (most Tier D packages).
 | Phase R — remove `NativeModules` fallback | PR-fallback | **closed** | **closed** | **closed** | done | `full` + RNFBDebug | `refactor: cleanup legacy arch native module fallback` | Proof 683/823/849 (`/tmp/rnfb-e2e-phaseR-proof-*.log`). Review 2026-07-03: no critical/serious. Android cold boot committed separately. |
 | Phase S gap-analysis | PS-gap | n/a | n/a | n/a | done | `none` | none | Completed 2026-07-03. First implementation slice: `app/registerVersion`; follow-ups: auth parser/TOTP URL, then perf metric controls. |
 | Phase S `app/registerVersion` sync parity | PS-app-registerVersion | **closed** | **closed** | **closed** | done | `area-focused` | `refactor(app): return sync parity for registerVersion` | Implemented 2026-07-03: `registerVersion(): void`, sync throw Jest assertion, removed stale `configs/app.ts` async-vs-sync entry. Green: `lerna:prepare`, `tsc:compile`, `tsc:compile:consumer`, focused app Jest 10/10, `reference:api`, `compare:types`, `lint:js`. Independent review: no findings; no e2e needed for type-only scope. |
-| Phase S auth parser/TOTP sync parity | PS-auth-parsers | **closed** | **closed** | **closed** | done | `area-focused` | `refactor(auth): return sync parity for auth parsers` | Sync `isSignInWithEmailLink` + `TotpSecret.generateQrCodeUrl`; native sync error shape; jest.setup; tests + e2e sync calls; compare-types + v26 doc. Validation: Jest 91/91, compare:types, lint, reference:api, codegen:verify exit 0. Android area e2e 159/15/0 (`/tmp/rnfb-e2e-android-auth-phaseS-final.log`). |
+| Phase S auth parser/TOTP sync parity | PS-auth-parsers | **closed** | **closed** | **closed** | done | `area-focused` | `refactor(auth): return sync parity for auth parsers` | Committed 2026-07-03. Sync `isSignInWithEmailLink` + `TotpSecret.generateQrCodeUrl`; native sync error shape; jest.setup; tests + e2e sync calls; compare-types + v26 doc. Validation: Jest 91/91, compare:types, lint, reference:api, codegen:verify exit 0. Android area e2e 159/15/0 (`/tmp/rnfb-e2e-android-auth-phaseS-final.log`). |
+| Phase S perf metric controls sync parity | PS-perf-metrics | **closed** | **closed** | **closed** | done | `area-focused` | `refactor(perf): return sync parity for metric controls` | Sync trace/http/screen start/stop; Android *Sync helpers; iOS sync shells. Jest 10/10; compare:types, lint, reference:api green. Review e2e iOS/Android 60/2/0 (`/tmp/rnfb-e2e-*-perf-review.log`). macOS N/A (module skip). Remediation: perf usage docs await removed. |
 
 ---
 

packages/perf/__tests__/nativeModuleContract.test.ts

@@ -12,25 +12,74 @@ const SPEC_METHODS = [
   'stopHttpMetric',
 ] as const;
 
+const SYNC_METHODS = [
+  'startTrace',
+  'stopTrace',
+  'startScreenTrace',
+  'stopScreenTrace',
+  'startHttpMetric',
+  'stopHttpMetric',
+] as const;
+
 describe('TurboModule wrapper contract (NewArch-AD-17.1)', function () {
-  it('exposes every spec method callable through the real wrapper', function () {
-    assertTurboContract({
-      namespace: 'perf',
-      nativeModuleName: 'NativeRNFBTurboPerf',
-      nativeEvents: false,
-      hasMultiAppSupport: false,
-      hasCustomUrlOrRegionSupport: false,
-      turboModule: true,
-      specMethods: SPEC_METHODS,
-      createMock: () => jest.fn(() => Promise.resolve(null)),
-      constants: {
-        isPerformanceCollectionEnabled: true,
-        isInstrumentationEnabled: true,
+  it('exposes every spec method callable through the real wrapper, with sync start/stop', function () {
+    assertTurboContract(
+      {
+        namespace: 'perf',
+        nativeModuleName: 'NativeRNFBTurboPerf',
+        nativeEvents: false,
+        hasMultiAppSupport: false,
+        hasCustomUrlOrRegionSupport: false,
+        turboModule: true,
+        specMethods: SPEC_METHODS,
+        createMock: method =>
+          jest.fn(() => {
+            if (SYNC_METHODS.includes(method as (typeof SYNC_METHODS)[number])) {
+              return undefined;
+            }
+            return Promise.resolve(null);
+          }),
+        constants: {
+          isPerformanceCollectionEnabled: true,
+          isInstrumentationEnabled: true,
+        },
+        assertExtra: wrapped => {
+          expect(wrapped.isPerformanceCollectionEnabled).toBe(true);
+          expect(wrapped.isInstrumentationEnabled).toBe(true);
+        },
       },
-      assertExtra: wrapped => {
-        expect(wrapped.isPerformanceCollectionEnabled).toBe(true);
-        expect(wrapped.isInstrumentationEnabled).toBe(true);
+      {
+        startTrace: wrapped => {
+          const result = wrapped.startTrace(0, 'trace');
+          expect(result).toBeUndefined();
+          expect(result).not.toBeInstanceOf(Promise);
+        },
+        stopTrace: wrapped => {
+          const result = wrapped.stopTrace(0, { metrics: {}, attributes: {} });
+          expect(result).toBeUndefined();
+          expect(result).not.toBeInstanceOf(Promise);
+        },
+        startScreenTrace: wrapped => {
+          const result = wrapped.startScreenTrace(0, 'screen');
+          expect(result).toBeUndefined();
+          expect(result).not.toBeInstanceOf(Promise);
+        },
+        stopScreenTrace: wrapped => {
+          const result = wrapped.stopScreenTrace(0);
+          expect(result).toBeUndefined();
+          expect(result).not.toBeInstanceOf(Promise);
+        },
+        startHttpMetric: wrapped => {
+          const result = wrapped.startHttpMetric(0, 'https://example.com', 'GET');
+          expect(result).toBeUndefined();
+          expect(result).not.toBeInstanceOf(Promise);
+        },
+        stopHttpMetric: wrapped => {
+          const result = wrapped.stopHttpMetric(0, { attributes: {} });
+          expect(result).toBeUndefined();
+          expect(result).not.toBeInstanceOf(Promise);
+        },
       },
-    });
+    );
   });
 });

packages/perf/__tests__/perf.test.ts

@@ -35,4 +35,47 @@ describe('Performance Monitoring', function () {
       expect(startScreenTrace).toBeDefined();
     });
   });
+
+  describe('synchronous start/stop parity', function () {
+    it('`Trace.start()` and `Trace.stop()` return synchronously (not Promises)', function () {
+      const perf = getPerformance();
+      const traceInstance = trace(perf, 'sync-trace');
+
+      const startResult = traceInstance.start();
+      expect(startResult).toBeUndefined();
+      expect(startResult).not.toBeInstanceOf(Promise);
+      // @ts-expect-error internal flag for test assertion only
+      expect(traceInstance._started).toBe(true);
+
+      const stopResult = traceInstance.stop();
+      expect(stopResult).toBeUndefined();
+      expect(stopResult).not.toBeInstanceOf(Promise);
+      // @ts-expect-error internal flag for test assertion only
+      expect(traceInstance._stopped).toBe(true);
+    });
+
+    it('`HttpMetric.start()` and `HttpMetric.stop()` return synchronously (not Promises)', function () {
+      const perf = getPerformance();
+      const metric = httpMetric(perf, 'https://example.com', 'GET');
+      metric.setHttpResponseCode(200);
+
+      const startResult = metric.start();
+      expect(startResult).toBeUndefined();
+      expect(startResult).not.toBeInstanceOf(Promise);
+
+      const stopResult = metric.stop();
+      expect(stopResult).toBeUndefined();
+      expect(stopResult).not.toBeInstanceOf(Promise);
+    });
+
+    it('`startTrace()` returns a started Trace synchronously (not a Promise)', function () {
+      const perf = getPerformance();
+      const traceInstance = (perf as unknown as { startTrace(name: string): unknown }).startTrace(
+        'sync-start-trace',
+      );
+
+      expect(traceInstance).not.toBeInstanceOf(Promise);
+      expect((traceInstance as { _started: boolean })._started).toBe(true);
+    });
+  });
 });