Migration Guide: cordova-plugin-firebasex → Modular Plugins

This guide covers migrating from the original monolithic cordova-plugin-firebasex plugin to the new modular plugin architecture.

Introduction
Modular Plugin Overview
Migration Paths
- Path A: Drop-in Wrapper (Minimal Changes)
- Path B: Individual Modular Plugins (Recommended)
Updating Your Code
- API Globals Reference
- Code Examples
Plugin Variables
Breaking Changes
Plugin Documentation

Introduction

The original cordova-plugin-firebasex bundled all Firebase services — Analytics, Messaging, Auth, Crashlytics, Firestore, Functions, Remote Config, Performance, and In-App Messaging — into a single monolithic plugin. Every app that used the plugin included the native SDKs for all services, regardless of which ones were actually used.

The new modular architecture splits the plugin into focused packages:

Smaller app size — Only the native Firebase SDKs you actually use are included in your binary. Apps that only need Messaging and Analytics can avoid bundling Firestore, Auth, and other unused SDKs.
Faster builds — Fewer native dependencies means shorter compilation and linking times, particularly on iOS where CocoaPods resolution is a bottleneck.
Flexible dependency management — Each plugin can be versioned and updated independently. You can upgrade Crashlytics without risking changes to Messaging, for example.
Clearer project structure — Each plugin has a focused scope, making it easier to understand configuration and troubleshoot issues.

Modular Plugin Overview

Plugin	Description
`cordova-plugin-firebasex-core`	Firebase initialization, installations, shared utilities. Required by all other plugins.
`cordova-plugin-firebasex-analytics`	Event logging, user properties, screen tracking, consent management.
`cordova-plugin-firebasex-messaging`	Push notifications (FCM), token management, notification channels, badge counts.
`cordova-plugin-firebasex-auth`	Email/password, phone, Google Sign-In, Apple Sign-In, anonymous auth, custom tokens, MFA.
`cordova-plugin-firebasex-crashlytics`	Crash reporting, non-fatal exceptions, custom keys/logs.
`cordova-plugin-firebasex-firestore`	Document CRUD, collection queries, real-time listeners, batch operations.
`cordova-plugin-firebasex-functions`	HTTPS callable Cloud Functions.
`cordova-plugin-firebasex-config`	Remote Config — fetch, activate, and read remote values.
`cordova-plugin-firebasex-performance`	Performance Monitoring — custom traces, HTTP metrics.
`cordova-plugin-firebasex-inappmessaging`	In-App Messaging (native SDK only, no JS API).

Migration Paths

Path A: Drop-in Wrapper (Minimal Changes)

If you want to migrate with zero code changes, use the wrapper plugin. It installs all 10 modular plugins behind the scenes and re-exports their APIs under the original FirebasePlugin global.

Step 1: Remove the old plugin

cordova plugin remove cordova-plugin-firebasex --nosave

Note: The --nosave flag prevents changes to config.xml and package.json, preserving your existing plugin variable entries.

Step 2: Install the wrapper

cordova plugin add cordova-plugin-firebasex@20

Note: Version 20.x.x of cordova-plugin-firebasex is the modular wrapper. It declares dependencies on all 10 sub-plugins and re-exports their APIs.

If you were passing plugin variables at install time, the wrapper accepts all the same variables and forwards them to the appropriate sub-plugins:

cordova plugin add cordova-plugin-firebasex@20 \
  --variable FIREBASE_ANALYTICS_WITHOUT_ADS=true \
  --variable IOS_ENABLE_APPLE_SIGNIN=true

Step 3: Build and test

Your existing code using FirebasePlugin.* will continue to work with no changes.

Path B: Individual Modular Plugins (Recommended)

For the full benefits of the modular architecture, install only the plugins you need.

Step 1: Remove the old plugin

cordova plugin remove cordova-plugin-firebasex

Step 2: Identify which services you use

Review your code for the Firebase features you actually call. Common patterns:

If you call...	You need...
`getToken()`, `onMessageReceived()`, `subscribe()`	`cordova-plugin-firebasex-messaging`
`logEvent()`, `setScreenName()`, `setUserProperty()`	`cordova-plugin-firebasex-analytics`
`signInWithEmailAndPassword()`, `getCurrentUser()`	`cordova-plugin-firebasex-auth`
`logError()`, `setCrashlyticsCustomKey()`	`cordova-plugin-firebasex-crashlytics`
`fetchDocumentInFirestoreCollection()`	`cordova-plugin-firebasex-firestore`
`callFunction()`	`cordova-plugin-firebasex-functions`
`fetch()`, `activateFetched()`, `getValue()`	`cordova-plugin-firebasex-config`
`startTrace()`, `stopTrace()`	`cordova-plugin-firebasex-performance`

Step 3: Install your chosen plugins

The core plugin is automatically installed as a dependency — you don't need to install it explicitly.

# Example: only Messaging and Analytics
cordova plugin add cordova-plugin-firebasex-messaging \
  --variable IOS_FCM_ENABLED=true

cordova plugin add cordova-plugin-firebasex-analytics \
  --variable FIREBASE_ANALYTICS_WITHOUT_ADS=true

Step 4: Update your code

Replace references from the old FirebasePlugin global to the new modular globals. See Updating Your Code below.

Step 5: Build and test

cordova build android
cordova build ios

Updating Your Code

API Globals Reference

When using individual modular plugins (Path B), each plugin exposes its own JavaScript global:

Old Global	New Global	Plugin
`FirebasePlugin`	`FirebasexCore`	`cordova-plugin-firebasex-core`
`FirebasePlugin`	`FirebasexAnalytics`	`cordova-plugin-firebasex-analytics`
`FirebasePlugin`	`FirebasexMessaging`	`cordova-plugin-firebasex-messaging`
`FirebasePlugin`	`FirebasexAuth`	`cordova-plugin-firebasex-auth`
`FirebasePlugin`	`FirebasexCrashlytics`	`cordova-plugin-firebasex-crashlytics`
`FirebasePlugin`	`FirebasexFirestore`	`cordova-plugin-firebasex-firestore`
`FirebasePlugin`	`FirebasexFunctions`	`cordova-plugin-firebasex-functions`
`FirebasePlugin`	`FirebasexConfig`	`cordova-plugin-firebasex-config`
`FirebasePlugin`	`FirebasexPerformance`	`cordova-plugin-firebasex-performance`

Note: The cordova-plugin-firebasex-inappmessaging plugin has no JS API — it only includes the native SDK.

Code Examples

Before (monolithic):

// All calls go through a single global
FirebasePlugin.getToken(function(token) {
    console.log("FCM token: " + token);
}, function(error) {
    console.error(error);
});

FirebasePlugin.logEvent("select_content", { content_type: "page", item_id: "home" });

FirebasePlugin.signInWithEmailAndPassword("user@example.com", "password123",
    function(user) { console.log("Signed in: " + JSON.stringify(user)); },
    function(error) { console.error(error); }
);

FirebasePlugin.logError("Something went wrong", function() {
    console.log("Error logged to Crashlytics");
});

After (modular):

// Each service has its own global
FirebasexMessaging.getToken(function(token) {
    console.log("FCM token: " + token);
}, function(error) {
    console.error(error);
});

FirebasexAnalytics.logEvent("select_content", { content_type: "page", item_id: "home" });

FirebasexAuth.signInWithEmailAndPassword("user@example.com", "password123",
    function(user) { console.log("Signed in: " + JSON.stringify(user)); },
    function(error) { console.error(error); }
);

FirebasexCrashlytics.logError("Something went wrong", function() {
    console.log("Error logged to Crashlytics");
});

Tip: If you use the wrapper plugin (Path A), you don't need to change any code — FirebasePlugin.* continues to work.

Plugin Variables

Variables by Plugin

Each modular plugin defines its own set of configurable variables. Below is the complete reference.

Core (`cordova-plugin-firebasex-core`)

Variable	Default	Description
`ANDROID_FIREBASE_CORE_VERSION`	`21.1.1`	Android Firebase BoM / core SDK version.
`ANDROID_FIREBASE_INSTALLATIONS_VERSION`	`18.0.0`	Android Firebase Installations SDK version.
`ANDROID_GSON_VERSION`	`2.13.2`	Google Gson library version for Android.
`IOS_FIREBASE_SDK_VERSION`	`12.9.0`	iOS Firebase SDK version (CocoaPods).

Analytics (`cordova-plugin-firebasex-analytics`)

Variable	Default	Description
`ANDROID_FIREBASE_ANALYTICS_VERSION`	`23.0.0`	Android Firebase Analytics SDK version.
`ANDROID_PLAY_SERVICES_TAGMANAGER_VERSION`	`18.3.0`	Android Play Services Tag Manager version.
`IOS_FIREBASE_SDK_VERSION`	`12.9.0`	iOS Firebase SDK version (for analytics pods).
`IOS_GOOGLE_TAG_MANAGER_VERSION`	`9.0.0`	iOS Google Tag Manager pod version.
`FIREBASE_ANALYTICS_COLLECTION_ENABLED`	`true`	Enable/disable analytics collection at startup.
`FIREBASE_ANALYTICS_WITHOUT_ADS`	`false`	Use `FirebaseAnalyticsWithoutAdIdSupport` pod (no IDFA).
`GOOGLE_ANALYTICS_ADID_COLLECTION_ENABLED`	`true`	Enable advertising ID collection.
`GOOGLE_ANALYTICS_DEFAULT_ALLOW_ANALYTICS_STORAGE`	`true`	Default consent for analytics storage.
`GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_STORAGE`	`true`	Default consent for ad storage.
`GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_USER_DATA`	`true`	Default consent for ad user data.
`GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_PERSONALIZATION_SIGNALS`	`true`	Default consent for ad personalization.
`IOS_ON_DEVICE_CONVERSION_ANALYTICS`	`false`	Enable on-device conversion analytics (iOS).

Messaging (`cordova-plugin-firebasex-messaging`)

Variable	Default	Description
`ANDROID_FIREBASE_MESSAGING_VERSION`	`25.0.1`	Android Firebase Messaging SDK version.
`ANDROID_ICON_ACCENT`	`#FFFFFF`	Default accent color for Android notification icons.
`FIREBASE_FCM_AUTOINIT_ENABLED`	`true`	Auto-initialize FCM on app launch.
`FIREBASE_MESSAGING_IMMEDIATE_PAYLOAD_DELIVERY`	`false`	Deliver notification payloads immediately (iOS).
`IOS_FCM_ENABLED`	`true`	Enable FCM on iOS.
`IOS_ENABLE_CRITICAL_ALERTS_ENABLED`	`false`	Enable critical alerts capability (iOS).
`IOS_FIREBASE_SDK_VERSION`	`12.9.0`	iOS Firebase SDK version (for messaging pod).

Auth (`cordova-plugin-firebasex-auth`)

Variable	Default	Description
`ANDROID_FIREBASE_AUTH_VERSION`	`24.0.1`	Android Firebase Auth SDK version.
`ANDROID_PLAY_SERVICES_AUTH_VERSION`	`21.5.1`	Android Play Services Auth version.
`ANDROID_CREDENTIALS_VERSION`	`1.5.0`	AndroidX Credentials library version.
`ANDROID_GOOGLEID_VERSION`	`1.2.0`	Google Identity library version.
`IOS_FIREBASE_SDK_VERSION`	`12.9.0`	iOS Firebase SDK version (for auth pod).
`SETUP_RECAPTCHA_VERIFICATION`	`false`	Add reversed client ID URL scheme for reCAPTCHA.
`IOS_ENABLE_APPLE_SIGNIN`	`false`	Add Apple Sign-In entitlement (iOS).
`IOS_GOOGLE_SIGIN_VERSION`	`9.0.0`	GoogleSignIn pod version (iOS).

Crashlytics (`cordova-plugin-firebasex-crashlytics`)

Variable	Default	Description
`ANDROID_FIREBASE_CRASHLYTICS_VERSION`	`20.0.4`	Android Firebase Crashlytics SDK version.
`ANDROID_FIREBASE_CRASHLYTICS_NDK_VERSION`	`20.0.4`	Android Firebase Crashlytics NDK version.
`IOS_FIREBASE_SDK_VERSION`	`12.9.0`	iOS Firebase SDK version (for crashlytics pod).
`FIREBASE_CRASHLYTICS_COLLECTION_ENABLED`	`true`	Enable/disable Crashlytics at startup.

Performance (`cordova-plugin-firebasex-performance`)

Variable	Default	Description
`ANDROID_FIREBASE_PERF_VERSION`	`22.0.2`	Android Firebase Performance SDK version.
`IOS_FIREBASE_SDK_VERSION`	`12.9.0`	iOS Firebase SDK version (for performance pod).
`FIREBASE_PERFORMANCE_COLLECTION_ENABLED`	`true`	Enable/disable performance collection.
`ANDROID_FIREBASE_PERFORMANCE_MONITORING`	`false`	Add Firebase Perf Gradle plugin (Android).
`ANDROID_FIREBASE_PERF_GRADLE_PLUGIN_VERSION`	`2.0.1`	Firebase Perf Gradle plugin version.

Firestore (`cordova-plugin-firebasex-firestore`)

Variable	Default	Description
`ANDROID_FIREBASE_FIRESTORE_VERSION`	`26.1.0`	Android Firebase Firestore SDK version.
`ANDROID_GRPC_OKHTTP`	`1.75.0`	Android gRPC OkHttp version (Firestore dependency).
`ANDROID_GSON_VERSION`	`2.13.2`	Google Gson library version (Firestore dependency).
`IOS_FIREBASE_SDK_VERSION`	`12.9.0`	iOS Firebase SDK version (for firestore pod).
`IOS_USE_PRECOMPILED_FIRESTORE_POD`	`false`	Use precompiled Firestore pod for faster builds.

Functions (`cordova-plugin-firebasex-functions`)

Variable	Default	Description
`ANDROID_FIREBASE_FUNCTIONS_VERSION`	`22.1.0`	Android Firebase Functions SDK version.
`ANDROID_GSON_VERSION`	`2.13.2`	Google Gson library version (Functions dependency).
`IOS_FIREBASE_SDK_VERSION`	`12.9.0`	iOS Firebase SDK version (for functions pod).

Config (`cordova-plugin-firebasex-config`)

Variable	Default	Description
`ANDROID_FIREBASE_CONFIG_VERSION`	`23.0.1`	Android Firebase Remote Config SDK version.
`IOS_FIREBASE_SDK_VERSION`	`12.9.0`	iOS Firebase SDK version (for config pod).

In-App Messaging (`cordova-plugin-firebasex-inappmessaging`)

Variable	Default	Description
`ANDROID_FIREBASE_INAPPMESSAGING_VERSION`	`22.0.2`	Android Firebase In-App Messaging SDK version.
`IOS_FIREBASE_SDK_BETA_VERSION`	`12.9.0-beta`	iOS Firebase SDK version (for inappmessaging pod).

Variable Resolution Order

Plugin variables are resolved using a layered override strategy (later layers take precedence):

plugin.xml defaults — Default values declared in each plugin's <preference> elements.
config.xml overrides — Values specified in <plugin><variable> elements in the project's config.xml.
package.json overrides — Values specified under cordova.plugins in the project's package.json (highest priority for build-time hooks).
CLI variables — Values passed via --variable at install time (highest priority for install-time hooks).

When using the wrapper plugin, variables specified under the wrapper's plugin ID (cordova-plugin-firebasex) in config.xml or package.json are also recognized by all modular plugins. The modular plugin's own ID takes precedence if both are present. This means existing config.xml entries like:

<plugin name="cordova-plugin-firebasex" spec="^20.0.0">
    <variable name="FIREBASE_ANALYTICS_WITHOUT_ADS" value="true" />
    <variable name="IOS_ENABLE_APPLE_SIGNIN" value="true" />
</plugin>

...will still be picked up by both the wrapper and the individual modular plugins.

Preserving Custom Variable Values

If you have custom plugin variable values in your project, make sure they are preserved during migration.

Check your config.xml for any <variable> elements under the old plugin entry:

<!-- Look for this in your config.xml -->
<plugin name="cordova-plugin-firebasex" spec="...">
    <variable name="FIREBASE_ANALYTICS_WITHOUT_ADS" value="true" />
    <variable name="SETUP_RECAPTCHA_VERIFICATION" value="true" />
    <!-- etc. -->
</plugin>

Check your package.json for variable overrides:

{
  "cordova": {
    "plugins": {
      "cordova-plugin-firebasex": {
        "FIREBASE_ANALYTICS_WITHOUT_ADS": "true",
        "SETUP_RECAPTCHA_VERIFICATION": "true"
      }
    }
  }
}

When using the wrapper (Path A): Your existing config.xml and package.json entries under the cordova-plugin-firebasex name will continue to work. The wrapper forwards variables to sub-plugins at install time, and each sub-plugin's hook scripts also check for variables under the wrapper's plugin ID as a fallback.

When using individual plugins (Path B): Move your variable values to the appropriate modular plugin entries:

<!-- config.xml — modular style -->
<plugin name="cordova-plugin-firebasex-analytics" spec="...">
    <variable name="FIREBASE_ANALYTICS_WITHOUT_ADS" value="true" />
</plugin>
<plugin name="cordova-plugin-firebasex-auth" spec="...">
    <variable name="SETUP_RECAPTCHA_VERIFICATION" value="true" />
</plugin>

// package.json — modular style
{
  "cordova": {
    "plugins": {
      "cordova-plugin-firebasex-analytics": {
        "FIREBASE_ANALYTICS_WITHOUT_ADS": "true"
      },
      "cordova-plugin-firebasex-auth": {
        "SETUP_RECAPTCHA_VERIFICATION": "true"
      }
    }
  }
}

Alternatively, pass variables at install time with --variable:

cordova plugin add cordova-plugin-firebasex-analytics \
  --variable FIREBASE_ANALYTICS_WITHOUT_ADS=true

Breaking Changes

When using the wrapper (Path A)

Minimum platform versions: The modular plugins require Cordova 12+, cordova-android 14+, and cordova-ios 7+. Ensure your project meets these requirements before upgrading.
No other breaking changes. The wrapper preserves the FirebasePlugin global and all method signatures.

When using individual plugins (Path B)

JavaScript globals have changed. FirebasePlugin is no longer available. Each plugin registers its own global (e.g., FirebasexMessaging, FirebasexAnalytics). You must update all call sites. See API Globals Reference.
Method signatures are unchanged. All methods accept the same arguments and return the same values as before. Only the object you call them on changes.
Plugin variables must be reassigned. Variables previously set for cordova-plugin-firebasex need to be moved to the appropriate modular plugin entries in your config.xml and/or package.json. See Preserving Custom Variable Values.
Minimum platform versions apply as described above.

General notes

GoogleService-Info.plist and google-services.json are still required in your project root. The core plugin handles copying them to the platform directories.
Custom FCM receivers (FirebasePluginMessageReceiver subclasses) still work. The messaging plugin includes the receiver manager infrastructure.
Notification icons and accent colors are configured via the messaging plugin's ANDROID_ICON_ACCENT variable and resource files, just as before.

Plugin Documentation

For detailed API documentation and configuration options, refer to each plugin's README:

Plugin	Documentation
Core	cordova-plugin-firebasex-core/README.md
Analytics	cordova-plugin-firebasex-analytics/README.md
Messaging	cordova-plugin-firebasex-messaging/README.md
Auth	cordova-plugin-firebasex-auth/README.md
Crashlytics	cordova-plugin-firebasex-crashlytics/README.md
Firestore	cordova-plugin-firebasex-firestore/README.md
Functions	cordova-plugin-firebasex-functions/README.md
Config	cordova-plugin-firebasex-config/README.md
Performance	cordova-plugin-firebasex-performance/README.md
In-App Messaging	cordova-plugin-firebasex-inappmessaging/README.md
Wrapper (backward-compat)	cordova-plugin-firebasex/README.md

Uh oh!

FilesExpand file tree

MIGRATION.md

Latest commit

History

MIGRATION.md

File metadata and controls

Migration Guide: cordova-plugin-firebasex → Modular Plugins

Table of Contents

Introduction

Modular Plugin Overview

Migration Paths

Path A: Drop-in Wrapper (Minimal Changes)

Step 1: Remove the old plugin

Step 2: Install the wrapper

Step 3: Build and test

Path B: Individual Modular Plugins (Recommended)

Step 1: Remove the old plugin

Step 2: Identify which services you use

Step 3: Install your chosen plugins

Step 4: Update your code

Step 5: Build and test

Updating Your Code

API Globals Reference

Code Examples

Plugin Variables

Variables by Plugin

Core (cordova-plugin-firebasex-core)

Analytics (cordova-plugin-firebasex-analytics)

Messaging (cordova-plugin-firebasex-messaging)

Auth (cordova-plugin-firebasex-auth)

Crashlytics (cordova-plugin-firebasex-crashlytics)

Performance (cordova-plugin-firebasex-performance)

Firestore (cordova-plugin-firebasex-firestore)

Functions (cordova-plugin-firebasex-functions)

Config (cordova-plugin-firebasex-config)

In-App Messaging (cordova-plugin-firebasex-inappmessaging)

Variable Resolution Order

Preserving Custom Variable Values

Breaking Changes

When using the wrapper (Path A)

When using individual plugins (Path B)

General notes

Plugin Documentation

Core (`cordova-plugin-firebasex-core`)

Analytics (`cordova-plugin-firebasex-analytics`)

Messaging (`cordova-plugin-firebasex-messaging`)

Auth (`cordova-plugin-firebasex-auth`)

Crashlytics (`cordova-plugin-firebasex-crashlytics`)

Performance (`cordova-plugin-firebasex-performance`)

Firestore (`cordova-plugin-firebasex-firestore`)

Functions (`cordova-plugin-firebasex-functions`)

Config (`cordova-plugin-firebasex-config`)

In-App Messaging (`cordova-plugin-firebasex-inappmessaging`)