Detects API drift between the firebase-js-sdk and the corresponding @react-native-firebase/* packages.
For each registered package it compares the modular public API exported by the firebase-js-sdk against the modular public API exported by the built RN Firebase package, then classifies every difference as one of:
| Category | Meaning |
|---|---|
| Missing in RN Firebase | Export exists in firebase-js-sdk but not in the RN package |
| Extra in RN Firebase | Export exists in the RN package but not in the firebase-js-sdk |
| Different shape | Same name, but the type signature or interface members differ |
Every difference must have an entry in the package's configs/<package-name>.ts explaining why it exists. The script exits with code 1, failing CI, if either:
- A difference is undocumented — add it to
configs/<package-name>.tswith a reason, or fix the RN Firebase types to match. - A config entry is stale — the API now matches the firebase-js-sdk, so the entry should be removed from
configs/<package-name>.ts.
A documented difference is not a free pass. Every missingInRN, extraInRN, and differentShape entry must clear one of the OKF change-authoring acceptable exceptions: an evidence-backed intractable technical reason (platform SDK, native bridge, Hermes/Metro, or toolchain limitation), or a user-accepted deferral with a documented rationale (e.g. an alignment that needs architectural review). Both require the user's explicit acceptance — convenience, "harmless", or optional-parameter drift never qualifies on its own:
missingInRN— an export we simply have not built yet is a backlog item, not a documented difference; only keep it here when it clears an acceptable exception.extraInRN— an RN-only export, overload, or parameter is drift, not a feature. If firebase-js-sdk does not expose it and no acceptable exception applies, remove it rather than documenting it.differentShape— align the RN Firebase types to firebase-js-sdk and remove the entry unless the shape difference is forced by an intractable reason (e.g. a native module that can only resolvePromise<null>) or a user-accepted deferral.
When implementing a missingInRN export, do not introduce new extraInRN / differentShape drift that would not itself clear an acceptable exception.
The root repository dependencies must be installed because the script reads the Firebase JS SDK types from the installed root node_modules/firebase package.
The RN Firebase package(s) must also be built before running the script, because the script reads from the compiled dist/typescript/lib/ files:
yarnFrom the repo root:
yarn compare:typesOr directly from this directory:
yarn install # first time only
yarn compare📦 remote-config
Extra in RN Firebase (12):
~ ConfigValues — RN Firebase-specific type alias ...
~ fetch — Legacy fetch API, prefer fetchConfig ...
...
Different shape (5):
~ getAll — Returns ConfigValues instead of Record<string, Value> ...
sdk: (RemoteConfig) => Record<string, Value>
rn: (RemoteConfig) => ConfigValues
...
✓ All 17 difference(s) are documented in configs/<name>.ts
📦 storage
Stale config entries (1):
✗ uploadString [STALE] — now matches the firebase-js-sdk; remove from configs/<name>.ts
✗ 1 stale config entry/entries — remove them from configs/<name>.ts
~ (yellow) = documented difference — CI passes.
✗ (red) = undocumented difference or stale config entry — CI fails.
src/
index.ts Entry point. Iterates packages, calls parse → compare → report.
parse.ts Uses ts-morph to read .d.ts files, resolve SDK re-export chains,
and extract typed export shapes.
compare.ts Diffs two export maps and classifies each difference.
Cross-references against the package config to split documented
from undocumented differences, and detects stale config entries
whose APIs now match the SDK.
report.ts Formats results to the terminal with colour coding.
registry.ts Package registry. Add new packages here.
types.ts TypeScript types for the config schema and internal data structures.
packages/
<package-name>/
(obsolete snapshots should not be added here)
configs/
<package-name>.ts Documented known differences for this package.
For each export, the parser extracts a normalised shape:
- function — ordered list of parameter types + return type (parameter names are ignored)
- interface — set of
{ name, type, optional }member descriptors (order-independent) - typeAlias — the raw type text (e.g.
'a' | 'b' | 'c') - variable — the type text
Shapes are compared as normalised strings. Semantically equivalent types that are textually different (e.g. Promise<null> vs Promise<void>, ConfigValues vs Record<string, Value>) will be flagged — this is intentional, so the config forces an explicit acknowledgement of every divergence.
The script reads Firebase JS SDK public declarations from the root node_modules/firebase package. Confirm the package exposes the modular public type entry in node_modules/firebase/package.json:
"./<package-name>": {
"types": "./<package-name>/dist/<package-name>/index.d.ts"
}
Those wrapper files often re-export public declarations from @firebase/<package-name>, and the parser resolves that chain through root node_modules.
Find the built modular type files for the RN Firebase package. They are usually at:
packages/<package-name>/dist/typescript/lib/types/[modular | PACKAGE_NAME].d.ts ← type definitions
packages/<package-name>/dist/typescript/lib/[modular | PACKAGE_NAME].d.ts ← function declarations
Check the package's package.json types field to confirm the dist location.
Also note any support files — files that are re-exported from the modular files and need to be in the ts-morph project for re-export resolution (e.g. statics.d.ts, types/internal.d.ts). Their exports are not compared directly.
Create configs/<package-name>.ts with a PackageConfig object:
import type { PackageConfig } from '../src/types';
const config: PackageConfig = {
// Rename mapping: sdkName → rnName (when an export has been renamed)
nameMapping: {
// 'SomeType': 'RNSomeType',
},
// Exports present in firebase-sdk but intentionally absent from RN Firebase
missingInRN: [
{
name: 'someWebOnlyFunction',
reason: 'Uses the Web Crypto API which is not available in React Native.',
},
],
// Exports present in RN Firebase but not in firebase-sdk
extraInRN: [
{
name: 'someNativeHelper',
reason: 'RN-specific helper with no web equivalent.',
},
],
// Exports present in both but with different type signatures
differentShape: [
{
name: 'someFunction',
reason: 'Returns Promise<null> instead of Promise<void> because the native module resolves with null.',
},
],
};
export default config;Leave any section as an empty array (or omit it) if there are no differences in that category.
Add an entry to src/registry.ts:
import newPackageConfig from '../configs/<package-name>';
// inside the packages array:
{
name: '<package-name>',
firebaseSdkTypesPaths: [firebaseTypes('<package-name>')],
rnFirebaseModularFiles: [
path.join(rnDist('<package-name>'), 'types', 'modular.d.ts'),
path.join(rnDist('<package-name>'), 'modular.d.ts'),
],
rnFirebaseSupportFiles: [
// add any .d.ts files needed to resolve re-exports (not compared directly)
path.join(rnDist('<package-name>'), 'statics.d.ts'),
],
config: newPackageConfig,
},Build the package and run the script. Any undocumented differences will be printed in red — add them to configs/<package-name>.ts with a reason, or fix the RN Firebase types to match the SDK.
# from repo root
yarn
yarn compare:typesWhen a new firebase-js-sdk version ships with type changes:
- Update the root
firebasedependency and runyarnfrom the repository root. - Run
yarn compare:types. - Any newly introduced differences will be flagged as undocumented. Either:
- Update the RN Firebase types to match, or
- Add a new entry to
configs/<package-name>.tsexplaining why the difference is intentional.
- Any config entries that the SDK change has now made redundant will be flagged as stale. Remove them from
configs/<package-name>.ts.
When the RN Firebase types are updated to match the firebase-js-sdk for a previously documented difference:
- Update the RN Firebase types and rebuild the package.
- Run
yarn compare:types. - The resolved entry will be flagged as stale (
✗ [STALE]). Remove it fromconfigs/<package-name>.ts.