Firebase for React Native

Two SDKs both called Firebase

Get this wrong and you'll spend a day wondering why Crashlytics reports nothing.

There are two ways to talk to Firebase from React Native, and they are not interchangeable. Most tutorials don't say which one they're using, which is why so much Firebase-in-RN advice silently fails.

For a production mobile app, React Native Firebase is the answer. The three products with the best effort-to-value ratio in all of Firebase — Crashlytics, Analytics, and Cloud Messaging — are native-only and simply do not exist in the JS SDK. There is no workaround; they instrument the OS, not your JavaScript.

The JS SDK earns its place in exactly two situations: a React Native Web build that also has to run in a browser, and SQL Connect, which has no native module. You can install both side by side in one app if you need to — they're separate packages reading the same project config — but keep one library per product, never two clients for the same Firestore.

How it actually runs

Four layers. Knowing where each one stops explains most Firebase bugs in React Native.

Your JavaScript never talks to Google. It calls a TurboModule, which calls the real Firebase SDK compiled into your app binary, which talks to Google. That indirection is the source of nearly every confusing symptom in RN Firebase — so it's worth holding in your head:

Three consequences fall straight out of that picture:

• Expo Go will never work. It's a pre-built binary containing a fixed set of native modules, and the Firebase SDKs aren't among them. Your calls hit a missing module and do nothing. This is not a bug and there's no flag for it.
• Adding a Firebase package means a rebuild. npm install plus Fast Refresh is not enough; new native code has to be compiled in.
• Authorisation lives server-side. Your JS bundle ships to strangers' phones and can be read. Firestore security rules, Cloud Functions and App Check decide what's allowed — never a check in your React code.

One more grouping worth knowing, because it predicts cost and offline behaviour. Data services (Firestore, Realtime DB, Storage) are two-way round trips billed per operation and cached on device. Engagement services (Messaging, Remote Config, In-App Messaging) push down to the device and are free. Telemetry services (Crashlytics, Analytics, Performance) only ever send upward, are free, and nothing comes back.

Wiring it up in Expo

Config plugins, not manual Gradle edits. Do this once and adding the next module is two lines.

With Expo's Continuous Native Generation, you don't hand-edit build.gradle or the Podfile — you declare config plugins in app.json and let prebuild write the native code. Every RNFirebase module ships one.

npx expo install @react-native-firebase/app \
  @react-native-firebase/analytics \
  @react-native-firebase/crashlytics \
  @react-native-firebase/messaging \
  @react-native-firebase/remote-config

{
  "expo": {
    "android": {
      "package": "com.example.app",
      // points at the file you downloaded from the console
      "googleServicesFile": "./google-services.json"
    },
    "ios": {
      "googleServicesFile": "./GoogleService-Info.plist"
    },
    "plugins": [
      "@react-native-firebase/app",          // must come first
      "@react-native-firebase/analytics",
      "@react-native-firebase/crashlytics",
      ["expo-build-properties", {
        "ios": { "useFrameworks": "static" }   // RNFirebase requires this on iOS
      }]
    ]
  }
}

One more file, easy to miss, and it's the reason people think Crashlytics is broken locally:

{
  "react-native": {
    // without this, Crashlytics is a no-op in debug builds
    "crashlytics_debug_enabled": true,
    "crashlytics_auto_collection_enabled": true,

    // useful when you need consent before any collection starts
    "analytics_auto_collection_enabled": true,
    "messaging_auto_init_enabled": true
  }
}

Then build. npx expo run:android compiles a dev client locally; eas build --profile development does it in the cloud. Either way you install that binary once and Metro serves your JS into it exactly like Expo Go — you only rebuild when native dependencies change.

One wrapper module, always

Before you scatter Firebase imports through your screens: put every @react-native-firebase/* import behind a single module of your own. It takes ten minutes and pays for itself three times — your tests mock one file instead of five packages, telemetry failures can be swallowed in one place (an analytics call must never break a user flow), and swapping or removing a product later is one file's work.

import { getAnalytics, logEvent as fbLogEvent } from '@react-native-firebase/analytics';
import { getCrashlytics, recordError as fbRecordError } from '@react-native-firebase/crashlytics';

const analytics = getAnalytics();
const crashlytics = getCrashlytics();

export function logEvent(name: string, params?: Record<string, unknown>): void {
  try { void fbLogEvent(analytics, name, params); } catch { /* never throw */ }
}

export function recordError(e: unknown): void {
  try { fbRecordError(crashlytics, e instanceof Error ? e : new Error(String(e))); } catch {}
}

Telemetry

Free, native-only, and the highest-value thing you can add. Start here.

import {
  getCrashlytics, recordError, log, setUserId, setAttributes,
} from '@react-native-firebase/crashlytics';

const crashlytics = getCrashlytics();

setUserId(crashlytics, accountId);           // opaque id, never an email
await setAttributes(crashlytics, {
  locale: 'hi',
  session_mode: 'guest',
});

// Breadcrumb + non-fatal. The log lands in the report's timeline.
try {
  await api.fetchForecast(id);
} catch (e) {
  log(crashlytics, `forecast failed for ${id}`);
  recordError(crashlytics, e as Error);
  showRetry();
}

import { getAnalytics, logScreenView, logEvent, setUserProperty }
  from '@react-native-firebase/analytics';

const analytics = getAnalytics();
const navRef = useNavigationContainerRef();
const previous = useRef<string>();

<NavigationContainer
  ref={navRef}
  onReady={() => { previous.current = navRef.getCurrentRoute()?.name; }}
  onStateChange={async () => {
    const name = navRef.getCurrentRoute()?.name;
    if (name && name !== previous.current) {       // de-dupe, or you double-count
      previous.current = name;
      await logScreenView(analytics, { screen_name: name, screen_class: name });
    }
  }}
/>

// Fire on the outcome, from the store method that owns it.
await logEvent(analytics, 'profile_created', { is_self: true, mode: 'account' });

// Durable traits become audience dimensions. Max 25 per project.
await setUserProperty(analytics, 'chart_style', 'north');

// GA limits, silently enforced: name ≤ 40 chars, ≤ 25 params,
// values ≤ 100 chars. Over-limit events are dropped with no error.

import { getPerformance, trace } from '@react-native-firebase/perf';

const t = trace(getPerformance(), 'panchang_compute');
await t.start();
const result = await computePanchang(date);
t.putAttribute('source', cached ? 'cache' : 'engine');
t.putMetric('yoga_count', result.yogas.length);
await t.stop();

Messaging & config

Changing what the app does, and what it says, without shipping a build.

import { getMessaging, setBackgroundMessageHandler }
  from '@react-native-firebase/messaging';

// Module scope. Not in a component, not in an effect.
setBackgroundMessageHandler(getMessaging(), async (message) => {
  await cachePanchang(message.data?.date);
});

import 'expo-router/entry';  // or registerRootComponent(App)

import {
  getMessaging, getToken, onMessage, onTokenRefresh, subscribeToTopic,
} from '@react-native-firebase/messaging';
import * as Notifications from 'expo-notifications';

const messaging = getMessaging();

// Ask at a moment where the value is obvious — not on first launch.
const { status } = await Notifications.requestPermissionsAsync();
if (status !== 'granted') return;

const token = await getToken(messaging);
await api.registerDevice(token);
onTokenRefresh(messaging, (t) => api.registerDevice(t));  // rotates on reinstall

// Topics beat per-device fan-out for broadcast content.
await subscribeToTopic(messaging, 'daily_panchang_hi');

// Foreground messages don't show a tray notification — you draw them.
const unsub = onMessage(messaging, async (m) => showInAppBanner(m.notification));

import {
  getRemoteConfig, setDefaults, setConfigSettings,
  fetchAndActivate, getBoolean, getNumber, onConfigUpdated,
} from '@react-native-firebase/remote-config';

const config = getRemoteConfig();

await setDefaults(config, {
  match_feature_enabled: false,
  free_profile_limit: 3,
});

await setConfigSettings(config, {
  // Default throttle is ~12 hours. Set 0 in dev or you'll
  // swear your console changes aren't working.
  minimumFetchIntervalMillis: __DEV__ ? 0 : 3600_000,
});

await fetchAndActivate(config);

if (getBoolean(config, 'match_feature_enabled')) showMatchTab();

// React to console changes mid-session
onConfigUpdated(config, () => fetchAndActivate(config));

Identity & abuse

Who the user is, and whether the caller is really your app.

import {
  getAuth, signInAnonymously, signInWithCustomToken,
  onAuthStateChanged, linkWithCredential, GoogleAuthProvider,
} from '@react-native-firebase/auth';

const auth = getAuth();

// Zero-friction start
if (!auth.currentUser) await signInAnonymously(auth);

// Or bridge your own backend's accounts
const { firebaseToken } = await api.login(email, password);
await signInWithCustomToken(auth, firebaseToken);

// Session state, as a hook
useEffect(() => onAuthStateChanged(auth, setUser), []);

Data & storage

Optional if you already have a backend — but this is the half of Firebase that costs money, so read the billing note.

import {
  getFirestore, collection, query, where, orderBy, onSnapshot, doc, setDoc,
} from '@react-native-firebase/firestore';

const db = getFirestore();

function useJournal(uid: string) {
  const [entries, setEntries] = useState<Entry[]>([]);

  useEffect(() => {
    const q = query(
      collection(db, 'journal'),
      where('ownerUid', '==', uid),
      orderBy('createdAt', 'desc'),
    );
    // Returning the unsubscribe is what stops the leak — and the bill.
    return onSnapshot(q, (snap) =>
      setEntries(snap.docs.map((d) => ({ id: d.id, ...d.data() }) as Entry)),
    );
  }, [uid]);

  return entries;
}

await setDoc(doc(db, 'journal', id), { ownerUid: uid, nature: 'good' });

rules_version = '2';
service cloud.firestore {
  match /databases/{db}/documents {
    match /journal/{entryId} {
      allow read, write: if request.auth != null
        && request.auth.uid == resource.data.ownerUid;
    }
  }
}

import { getStorage, ref, putFile, getDownloadURL } from '@react-native-firebase/storage';

const r = ref(getStorage(), `avatars/${uid}.jpg`);
const task = putFile(r, localUri);        // a local file path, not a blob

task.on('state_changed', (s) =>
  setProgress(s.bytesTransferred / s.totalBytes));

await task;
const url = await getDownloadURL(r);

Server-side logic

For work that must not happen on a phone.

// App
import { getFunctions, httpsCallable } from '@react-native-firebase/functions';

const createOrder = httpsCallable(getFunctions(), 'createOrder');
const { data } = await createOrder({ cartId });

// ── functions/src/index.ts ──────────────────────────────
export const createOrder = onCall({ enforceAppCheck: true }, async (req) => {
  if (!req.auth) throw new HttpsError('unauthenticated', 'Sign in');
  return { orderId: await charge(req.auth.uid, req.data.cartId) };
});

// Scheduled push, no server of yours involved
export const dailyPanchang = onSchedule('0 6 * * *', async () => {
  await getMessaging().send({
    topic: 'daily_panchang_hi',
    notification: { title: todayTithi(), body: todaySummary() },
  });
});

AI

One product, and it replaced three older ones.

import { getApp } from '@react-native-firebase/app';
import { getAI, getGenerativeModel, GoogleAIBackend } from '@react-native-firebase/ai';

const ai = getAI(getApp(), {
  backend: new GoogleAIBackend(),
  appCheck: appCheckInstance,          // do not ship without this
});

const model = getGenerativeModel(ai, { model: 'gemini-3.8-flash' });

const result = await model.generateContent(
  `Explain this chart in simple Hindi: ${JSON.stringify(chart)}`,
);
setAnswer(result.response.text());

Release & testing

Two console products, no app code.

App Distribution ships pre-release builds straight to named testers, outside Play's review and track system — an email, a small tester app, and each build lands on their phone. It plugs into EAS and CI, so a merge can be on your QA team's devices in minutes. Note that Expo's own internal distribution covers much of the same ground, so this is worth adding mainly if you want Firebase's tester management and in-app update prompts.

Test Lab runs your app on real physical devices in Google's data centre. Robo test needs no test code at all — it crawls your UI and reports crashes with video — while instrumentation mode runs your suite across a device matrix in parallel. For RN this is the cheapest way to find the crash that only happens on one OEM's skin without buying that phone. If you're already running Maestro flows, those are the natural thing to point at it.

Full module matrix

Every package in the org at v26.4.0, and what it's for. Bookmark this bit.

Two things Firebase has that RNFirebase doesn't: SQL Connect (JS SDK only) and Hosting / App Hosting (web deployment — though you may still want Hosting for your privacy policy URL, which Play requires, and for the assetlinks.json file behind Android App Links).

What it costs

Two plans. The trap isn't the price — it's which axis you're billed on.

Spark is free with hard caps: no payment method, and service stops when you hit a limit. Blaze is pay-as-you-go — same free allowances, then usage above them — and it's required for Cloud Functions, for any outbound network call from a function, and for most newer products. New Blaze accounts typically get $300 of Google Cloud credit.

The good news for a mobile app: the entire telemetry and engagement half is free at any scale. Analytics, Crashlytics, Performance, Cloud Messaging, Remote Config, A/B Testing, In-App Messaging, App Distribution and App Check never bill on usage. You can run a large app on Spark indefinitely if you don't touch the data products.

Gone and going

Most RN Firebase tutorials online reference at least one of these. Check the date on anything you read.

RN-specific traps

The failures that are about React Native, not about Firebase.

• Testing in Expo Go. Every native Firebase call silently no-ops. You need a dev build. This accounts for most "my events don't show up" threads.
• Forgetting Analytics DebugView. Events batch for up to an hour by default, and the standard Events report lags about 24 hours — never use it to verify a new event. Turn on debug mode (adb shell setprop debug.firebase.analytics.app <package>) and watch DebugView, which is near-instant.
• Crashlytics silent in debug. Without crashlytics_debug_enabled in firebase.json, recordError does nothing locally and you'll conclude it's broken. Also: non-fatals upload on the next launch, so kill and reopen the app before checking.
• Background message handler inside a component. It must be at module scope in your entry file. Foreground will work, background won't, and the difference is easy to miss in testing.
• Unmocked native modules in Jest. The native modules don't exist in the test environment, so any suite that transitively imports your telemetry module explodes. Mock the Firebase packages globally in your Jest setup file — another reason for the single wrapper module.
• Listeners without cleanup. onSnapshot, onMessage and onAuthStateChanged all return an unsubscribe function. Return it from useEffect. Firestore listeners that leak also bill.
• Mixing the two SDKs for one product. Installing both firebase and @react-native-firebase/firestore and using both gives you two independent clients, two caches, and desync bugs that look like ghosts.
• One Firebase project for dev and prod. Use separate projects with separate config files per build profile. Test data mixed into production analytics is very hard to undo.
• Skipping the Local Emulator Suite. firebase emulators:start runs Firestore, Auth, Functions and Storage locally — free, instant, and the only sane way to iterate on security rules. Point the app at it with connectFirestoreEmulator in dev.
• iOS without useFrameworks: "static". RNFirebase requires it. The pod install error it produces otherwise doesn't mention Firebase at all.

A worked example

Jyotisha, a Hindu calendar app: Expo 54, RN 0.81.5, RNFirebase 26.4.0, Android-only, Spark plan.

Abstract advice is easy to agree with and hard to act on, so here is a real app at the two-product stage — Analytics and Crashlytics wired, nothing else. It gets the things right that usually go wrong: latest RNFirebase, modular API throughout, every Firebase import isolated in one telemetry.ts, both packages mocked globally in Jest, and crashlytics_debug_enabled set so local testing actually reports. Events sit at the store layer on outcomes rather than on button presses — the right call, and the one most teams get wrong. Nothing in the traps list above applies to it.

So the interesting question is what comes next. On the free plan, in rough order of value per unit of effort:

1. 01Remote ConfigFree, no new native surface beyond the package, and it gives you a kill switch plus flags for shipping half-finished features dark. The one to add first — it changes how you release, not just what you measure.
2. 02Cloud MessagingDaily panchang and tithi notifications are the obvious fit, and topics (daily_panchang_hi, daily_panchang_en) mean you don't need to store device tokens at all. Sending on a schedule needs a Cloud Function, which needs Blaze — or your existing backend can call the FCM HTTP API instead and keep you on Spark.
3. 03User propertiesMissing today. chart_style, locale and session_mode turn every existing report into a segmented one for about ten lines of code — the cheapest item on this list.
4. 04Performance MonitoringFree, and it would show what the forecast run and the astrology engine calls actually cost on a mid-range phone in India, rather than on a developer's emulator.
5. 05App CheckWorth it once anything on the backend costs money per call. Lower priority while Firebase is only receiving telemetry.

Firestore, Storage and Auth are the ones to leave alone here. The app already has a backend that owns accounts and profile data, and adding Firebase's versions would buy two sources of truth and a reconciliation problem — a worse trade than the offline sync is worth. That calculus is the general lesson: adopt the free telemetry and engagement half eagerly, and the data half only when you actually need what it does.