Переход с API с пространством имен на модульное приложение

Если в вашем приложении используется Firebase Web API с пространством имен (из библиотек compat или более ранних версий), рекомендуем перейти на модульный API, следуя инструкциям в этом руководстве.

В этом руководстве предполагается, что вы знакомы с API с пространством имен и будете использовать сборщик модулей, например webpack или Rollup, для обновления и дальнейшей разработки модульного приложения.

Настоятельно рекомендуем использовать сборщик модулей в среде разработки. Если вы не используете сборщик, то не сможете воспользоваться основным преимуществом модульного API – уменьшением размера приложения. Для установки SDK вам понадобится npm или yarn.

В этом руководстве мы будем использовать в качестве примера воображаемое веб-приложение, в котором используются SDK Authentication и Cloud Firestore. Примеры помогут вам понять концепции и практические шаги, необходимые для обновления всех поддерживаемых веб-SDK Firebase.

О библиотеках с пространством имен (compat)

Для Firebase Web SDK доступны два типа библиотек:

  • Модульный. Новый API, который позволяет удалять неиспользуемый код, чтобы сделать веб-приложение как можно меньше и быстрее.

  • Пространство имен (compat). Знакомый API, полностью совместимый с более ранними версиями SDK. Позволяет выполнить обновление, не меняя весь код Firebase сразу. Библиотеки совместимости практически не имеют преимуществ в размере или производительности по сравнению с аналогами в пространстве имен.

В этом руководстве предполагается, что вы будете использовать библиотеки совместимости, чтобы упростить обновление. Эти библиотеки позволяют использовать код с пространствами имен наряду с кодом, рефакторинг которого выполнен для модульного API. Это упростит компиляцию и отладку приложения в процессе обновления.

Для приложений, которые мало взаимодействуют с Firebase Web SDK (например, только вызывают API Authentication), может быть целесообразно провести рефакторинг старого кода с пространствами имен без использования библиотек совместимости. Если вы обновляете такое приложение, следуйте инструкциям в этом руководстве для модульного API, не используя библиотеки совместимости.

О процессе обновления

Каждый этап обновления ограничен, чтобы вы могли завершить редактирование исходного кода приложения, а затем скомпилировать и запустить его без сбоев. Подводя итог, вот что вы сделаете, чтобы обновить приложение:

  1. Добавьте в приложение модульные библиотеки и библиотеки совместимости.

  2. Обновите операторы импорта в коде, чтобы обеспечить совместимость.

  3. Проведите рефакторинг кода для одного продукта (например, Authentication) в модульном стиле.

  4. Необязательно. Удалите Authentication библиотеку и код совместимости для Authentication, чтобы уменьшить размер приложения для Authentication.

  5. Проведите рефакторинг функций для каждого продукта (например, Cloud Firestore, FCM и т. д.) в модульном стиле, компилируя и тестируя их, пока не будут завершены все области.

  6. Обновите код инициализации до модульного стиля.

  7. Удалите из приложения все оставшиеся инструкции и код совместимости.

Получите последнюю версию SDK

Для начала получите модульные библиотеки и библиотеки совместимости с помощью npm:

npm i firebase@13.4.0

# OR

yarn add firebase@13.4.0

Обновить импорт для совместимости

Чтобы код работал после обновления зависимостей, измените операторы импорта так, чтобы они использовали совместимую версию каждого импорта. Пример:

Раньше: версия 8 или более ранняя

import firebase from 'firebase/app';
import 'firebase/auth';
import 'firebase/firestore';

После: compat

// compat packages are API compatible with namespaced code
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
import 'firebase/compat/firestore';

Рефакторинг в модульный стиль

Хотя API с пространством имен основаны на шаблоне сервиса и пространства имен с точкой, модульный подход означает, что ваш код будет организован в основном вокруг функций. В модульном API пакет firebase/app и другие пакеты не возвращают полный экспорт, содержащий все методы из пакета. Вместо этого пакеты экспортируют отдельные функции.

В модульном API сервисы передаются в качестве первого аргумента, а затем функция использует сведения о сервисе для выполнения остальных действий. В примерах ниже показано, как провести рефакторинг вызовов API Authentication и Cloud Firestore.

Пример 1. Рефакторинг функции Authentication

До: compat

Код совместимости идентичен коду пространства имен, но импорт изменился.

import firebase from "firebase/compat/app";
import "firebase/compat/auth";

const auth = firebase.auth();
auth.onAuthStateChanged(user => {
  // Check for user status
});

После: модульный подход

Функция getAuth принимает firebaseApp в качестве первого параметра. Функция onAuthStateChanged не связана с экземпляром auth, как это было бы в API с пространством имен. Вместо этого используется свободная функция, которая принимает auth в качестве первого параметра.

import { getAuth, onAuthStateChanged } from "firebase/auth";

const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
  // Check for user status
});

Обновление обработки метода аутентификации getRedirectResult

Модульный API вносит критическое изменение в getRedirectResult. Если операция перенаправления не вызывается, модульный API возвращает null, а API с пространством имен – UserCredential с пользователем null.

До: compat

const result = await auth.getRedirectResult()
if (result.user === null && result.credential === null) {
  return null;
}
return result;

После: модульный подход

const result = await getRedirectResult(auth);
// Provider of the access token could be Facebook, GitHub, etc.
if (result === null || provider.credentialFromResult(result) === null) {
  return null;
}
return result;

Пример 2. Рефакторинг функции Cloud Firestore

До: compat

import "firebase/compat/firestore"

const db = firebase.firestore();
db.collection("cities").where("capital", "==", true)
    .get()
    .then((querySnapshot) => {
        querySnapshot.forEach((doc) => {
            // doc.data() is never undefined for query doc snapshots
            console.log(doc.id, " => ", doc.data());
        });
    })
    .catch((error) => {
        console.log("Error getting documents: ", error);
    });

После: модульный подход

Функция getFirestore принимает firebaseApp в качестве первого параметра, который был возвращен из initializeApp в предыдущем примере. Обратите внимание, что код для формирования запроса в модульном API сильно отличается. В частности, отсутствует цепочка, а такие методы, как query или where, теперь представлены как свободные функции.

import { getFirestore, collection, query, where, getDocs } from "firebase/firestore";

const db = getFirestore(firebaseApp);

const q = query(collection(db, "cities"), where("capital", "==", true));

const querySnapshot = await getDocs(q);
querySnapshot.forEach((doc) => {
  // doc.data() is never undefined for query doc snapshots
  console.log(doc.id, " => ", doc.data());
});

Обновите ссылки на Firestore DocumentSnapshot.exists

В модульном API появилось критическое изменение: свойство firestore.DocumentSnapshot.exists заменено на метод. Функциональность по сути та же (проверка существования документа), но вам необходимо провести рефакторинг кода, чтобы использовать более новый метод, как показано ниже:

Before:compat

if (snapshot.exists) {
  console.log("the document exists");
}

После: модульный подход

if (snapshot.exists()) {
  console.log("the document exists");
}

Пример 3. Сочетание стилей кода с пространствами имен и модулями

Использование библиотек совместимости во время обновления позволяет продолжать использовать код с пространством имен наряду с кодом, реорганизованным для модульного API.

Это значит, что вы можете сохранить существующий код с пространством имен для Cloud Firestore, пока вы проводите рефакторинг Authentication или другого кода Firebase SDK в модульный стиль, и при этом успешно компилировать приложение с обоими стилями кода.

То же самое относится к коду API с пространствами имен и модульному коду API внутри продукта, например Cloud Firestore. Новые и старые стили кода могут сосуществовать, если вы импортируете пакеты совместимости.

import firebase from 'firebase/compat/app';
import 'firebase/compat/firestore';
import { getDoc } from 'firebase/firestore'

const docRef = firebase.firestore().doc();
getDoc(docRef);

Обратите внимание, что, хотя ваше приложение будет компилироваться, вы не получите преимуществ в размере приложения от модульного кода, пока полностью не удалите операторы совместимости и код из своего приложения.

Обновите код инициализации

Обновите код инициализации приложения, чтобы использовать модульный синтаксис. Обновлять этот код нужно после того, как вы завершите рефакторинг всего кода в приложении. Это связано с тем, что firebase.initializeApp() инициализирует глобальное состояние как для совместимого, так и для модульного API, а модульная функция initializeApp() инициализирует только состояние для модульного API.

До: compat

import firebase from "firebase/compat/app"

firebase.initializeApp({ /* config */ });

После: модульный подход

import { initializeApp } from "firebase/app"

const firebaseApp = initializeApp({ /* config */ });

Удалить код совместимости

Чтобы воспользоваться преимуществами модульного API, связанными с размером, вам нужно преобразовать все вызовы в модульный стиль, показанный выше, и удалить все операторы import "firebase/compat/* из кода. После этого в коде не должно остаться ссылок на глобальное пространство имен firebase.* или другой код в стиле API с пространством имен.

Используйте библиотеку совместимости из окна

Модульный API оптимизирован для работы с модулями, а не с объектом window браузера. В предыдущих версиях библиотеки загрузка Firebase и управление им выполнялись с помощью пространства имен window.firebase. Однако в дальнейшем мы не рекомендуем использовать этот способ, поскольку он не позволяет удалять неиспользуемый код. Однако совместимая версия JavaScript SDK работает с window, если разработчики не хотят сразу переходить на модульную версию.

<script src="https://www.gstatic.com/firebasejs/13.4.0/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/13.4.0/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/13.4.0/firebase-auth-compat.js"></script>
<script>
   const firebaseApp = firebase.initializeApp({ /* Firebase config */ });
   const db = firebaseApp.firestore();
   const auth = firebaseApp.auth();
</script>

Библиотека совместимости использует модульный код и предоставляет его с тем же API, что и API с пространством имен. Это значит, что вы можете использовать документацию по API с пространством имен и фрагменты кода с пространством имен. Этот метод не рекомендуется для долгосрочного использования, но подходит для начала перехода на полностью модульную библиотеку.

Преимущества и ограничения модульного SDK

Полностью модульный SDK имеет следующие преимущества по сравнению с более ранними версиями:

  • Модульный SDK позволяет значительно уменьшить размер приложения. В ней используется современный формат модулей JavaScript, который позволяет импортировать только те артефакты, которые нужны вашему приложению. В зависимости от приложения, удаление неиспользуемого кода с помощью модульного SDK может привести к уменьшению размера на 80 % по сравнению с аналогичным приложением, созданным с использованием API с пространством имен.

  • Модульный SDK будет и дальше получать новые функции, а API с пространством имен – нет.