RFC: Deprecating Namespaced Compat APIs for the Firebase JS SDK

[hsubox76]

TLDR

We're looking for user feedback about the usage of the modular vs compat APIs which we will take into account before making any big changes. If you don't have any time for lengthy feedback, you can still vote in the poll at bottom about which API you're currently using.

Background

On August 25, 2021, we released version 9 of the Firebase Web SDK which introduced a new, tree-shakeable, modular API. In order to avoid overly disrupting existing users, we continued to provide the previous namespaced API through compat packages, which are in fact wrappers around the modular code.

The intention at the time was that the compat packages would be a temporary measure to allow users to gradually migrate to the modular API. However, we've heard from some users that there are still some drawbacks to the modular API that prevent them from wanting to fully migrate, so we want to pause that plan and get more feedback from users before making any decisions.

Modular/Compat Feature Parity

While the compat packages wrap all features of the Firebase Web SDK that existed as of the version 9 release, all new features from that date on are only being added to the modular API and will not be available to compat users. Bug fixes and internal tweaks will be propagated to compat because as a wrapper, it will automatically pick them up.

Some recent features only available in the modular API:

• Firestore's count() aggregation query
• Firestore OR queries
• Firestore Lite
• ReCAPTCHA Enterprise support in Auth
• MFA TOTP (Time-based one-time password)
• Ability to initialize debug mode in initializeAppCheck() instead of with an environment variable.
• Analytics methods setDefaultEventParameters(), setConsent(), and getGoogleAnalyticsClientId()

User Issues With The Modular API

Here's a list of issues we've heard from users that prevent them from migrating, and we invite you to add any more we haven't mentioned:

1. No time to go through and rewrite.
2. The compat API allows easier autocomplete assistance in IDEs
3. Some users rely on non-bundling environments (importing through <script> tags, using the CDN)
4. Complex Firestore queries are much easier to read in chaining format - subcollections are particularly difficult. (See some tips here.)
5. Not all browsers fully support ES modules in service workers.

Possible Solutions To User Issues

We have brainstormed a number of potential solutions to some of those issues. We would like your feedback on if any of these sound like they would solve the issue from your perspective, plus any other ideas you have that we haven't thought of.

1. Set a long deprecation timeline to give users more time to migrate.
2. A VSCode extension that provides some autocomplete/snippet functionality for the modular methods, that was lost when moving away from namespaced APIs.
3. A query builder tool for Firestore - the exact form factor to be determined.

What We Need Feedback On

We'd like to hear from users:

1. If you don't want to (or can't) migrate to the modular API, we'd love to hear why (see what details we're looking for below). If you've already migrated and you don't have any issues, we'd like to hear from you too.
2. If you haven't migrated, or have migrated with some reservations, we'd like to hear which of the reasons above is the blocker, or any reasons not listed.
3. If you've listed some blockers that prevent you from migrating, we'd like to hear any suggestions or ideas you might have on what features or tools we could provide that would remove that blocker, whether it's one of the possible solutions listed above, or something we haven't thought of.

Example Feedback

Here's an example of feedback that would be really helpful to us:

"I haven't migrated to the modular API because of reasons (1) and (4) (our codebase is large and we haven't had time for a full rewrite, and we are having trouble structuring complex Firestore queries in the new API. We also have a reason not on your list - we have to support [uncommon OS used on smart TVs] which doesn't work with v9. Solutions (1) and (3) sound great - would give us time to migrate, and the query builder would really improve DX for us around Firestore queries."

Or:

"We migrated a year ago, everything is fine, but I do miss autocomplete."

What We'll Do With The Feedback

We won't make any sudden changes, and will wait at least 6 months to let as many users weigh in as possible. If we start narrowing down options, we'll update this post and ask for continuing feedback on the new set of options. If we do make a decision to remove anything, we will give a deprecation notice at least one year before removing it.

Thanks ahead of time to everyone leaving feedback, and feel free to share with other Firebase users so we can hear back from as many as possible.

[ishowta]

There is a desire to share code with firebase-admin (and react-native-firebase), especially regarding firestore.
I can understand the argument that code should not be shared because the specifications and interfaces are slightly different, but the benefits are greater.

Currently we achieve this by using firebase-js-sdk v9 compat or by modularize firebase-admin ourselves (like this https://gist.github.com/ishowta/c769aefa037ae43ef87bc4eb905c6d5b).

We plan to continue using compatibility layers, whether official or unofficial.

[rosslavery]

Just commenting to say we've found the modular API very painful and challenging to migrate to. To the point where we've given up for the time being.

We have a large Angular app that we intentionally added a service to act as a layer of abstraction around the Firebase API, as a general best practice to avoid situations like this.

Unfortunately the new API is so drastic a change that it requires bit-by-bit migration (nested function calls and whatnot).

It's honestly just a really painful, unpleasant developer experience. Very little ability to use IDE autocomplete, which means needing to keep the docs page open just to see which files need importing to construct the nesting necessary to make things work. The "inside out" counterintuitive way you have to think to retrieve documents, the list goes on.

This Reddit thread has similar sentiment shared.

I am well aware of the numerous benefits of tree shaking and it's positive effects on bundle size. I would argue developer experience is also crucial, or people will simply find something easier to work with.

We aren't in a position to make that choice, there's simply too much to migrate, thus why I made this post 😅

[gianmd]

Transitioning to the new modular API has been a significant challenge for us, especially with our larger applications. The shift from using chained methods to nested functions is not a straightforward process. It's not as simple as a quick search and replace; it requires a complete overhaul and rethinking of our existing code. Each piece of code demands a thorough understanding and meticulous rewriting to achieve the same functionality as before.

One of the key issues we're facing is the inverted logic of the modular API. Now, it's essential to know the specific operation before even accessing a document. eg. update(doc(collection(db)))

This change is not always intuitive, especially when trying to determine which operations are available for a particular database action or document. The lack of method autocompletion exacerbates this issue. Previously, autocompletion made it easier to discover available actions. Now, we have to be familiar with all possible methods beforehand, adding an extra layer of complexity to our development process.

I understand some of the benefits but definitely the developer experience is compromised, making me to look other database solutions.

[Reza-1]

I like namespaced API because it is closer to Object Oriented style of programming which I'm more used to it.
To me this db.collection("cities").get() looks much cleaner than getDocs(collection(db, "cities"))
Classes have always been a better way for encapsulation and separation of concerns.
Why OOD had to be dropped when creating modules is a head-scratcher for me. Specially when OOD is all about modular design.

[marcusx2]

If the compat api gets deprecated, how will we be able to use firebase-messaging-sw.js service worker on a browser environment?

[harshit-j]

Legacy namespaced API is also available in v12 firebase-admin node.js SDK. Is it planned to remove it as well? Is there any timeline for this?

[ackvf]

There is no reason to migrate to modular api on backend where you are not limited by anything.

[basvandorst]

We won't make any sudden changes, and will wait at least 6 months to let as many users weigh in as possible. If we start narrowing down options, we'll update this post and ask for continuing feedback on the new set of options. If we do make a decision to remove anything, we will give a deprecation notice at least one year before removing it.

@hsubox76 8 months ago since this post, any update on this RFC/deprecation?

Personal experience: we are currently moving away from the compat API and I have to agree with the other people earlier in this thread; the new modular API is less intuitive (eg: code completion in IDE), sometimes confusing (eg: ref which is in @angular/fire/storage | @angular/fire/database)

[ackvf]

I haven't used firebase for several years and now I am starting a new project with it. The new modular api is very confusing for me and I am practically unable to write anything without first searching on the internet for what now feels like hours. Whereas previously I could just invoke intellisense at any point of the chain and get going, figuring out things on the way. Though, I do love tree-shaking.

I have actually found this thread when searching for how I can get back to the namespaced api, since I am progressing very slowly with the modular approach.

[weijian6791]

I use Expo and Firebase SDK for my mobile app. It is a small project so I personally do not care about the size and do not want to do the extra work to migrate from compat to modular. If I have to do it then I will do it. It is confusing now whether it is absolutely necessary. Would it be possible to have a vscode extension or copilot to help the migration?

[wernerkotze]

Not realistic for us to migrate to the Modular API. The effort required is just to much.

Would be nice to have clarity around timelines?

[paour]

We use React Native Firebase, which exposes the native Android and iOS libraries to React Native. Since the native libs use the namespaced API, the JS bindings also do.

When we build an app for mobile and the web, we shim the JS bindings so that they use the compat JS Firebase library instead. This can only work while the compat version exists.