Os usuários com apps que atualmente usam o SDK da Web do Firebase versão 8 ou anterior precisam considerar a migração para a versão 9 usando as instruções deste guia.
Ao seguir estas instruções, supomos que você já conhece a versão 8 e que vai aplicar um bundler de módulo, como webpack ou Rollup (links em inglês), para fazer upgrade e usar a versão 9.
Use um bundler de módulo no seu ambiente de desenvolvimento. Se você não usar um, não vai conseguir aproveitar os principais benefícios da versão 9 no tamanho reduzido do app. Você precisará de npm ou yarn para instalar o SDK.
As etapas de upgrade neste guia serão baseadas em um app da Web imaginário que usa os SDKs do Authentication e do Cloud Firestore. Conferindo os exemplos, é possível dominar os conceitos e as etapas práticas necessárias para fazer upgrade de todos os SDKs da Web do Firebase com suporte.
Sobre as bibliotecas de compatibilidade
Há dois tipos de bibliotecas disponíveis para o SDK da Web do Firebase versão 9:
- Modular: uma nova plataforma de API criada para facilitar o tree-shaking (remoção de código não utilizado). Assim, seu app da Web fica menor e mais rápido.
- Compatibilidade: uma plataforma de API conhecida que é totalmente compatível com o SDK da versão 8, permitindo que você faça upgrade para a versão 9 sem alterar todo o código do Firebase de uma só vez. Quase não há diferenças de tamanho ou desempenho entre essas bibliotecas e as usadas na versão 8.
Este guia pressupõe que você aproveitará as bibliotecas de compatibilidade da versão 9 para facilitar seu upgrade. Essas bibliotecas permitem que você continue usando o código da versão 8 com o código refatorado para a versão 9. Isso significa que você pode compilar e depurar seu app mais facilmente enquanto trabalha no processo de upgrade.
No caso de apps com uma exposição muito pequena ao SDK da Web do Firebase (por exemplo, um app que faz apenas uma chamada simples para as APIs do Authentication), pode ser prático refatorar o código da versão 8 sem usar as bibliotecas de compatibilidade da versão 9. Se você estiver fazendo upgrade desse app, siga as instruções do guia para a "versão 9 modular" sem usar as bibliotecas de compatibilidade.
Sobre o processo de upgrade
O escopo de cada etapa do upgrade é definido para que você possa terminar de editar o código-fonte do app e, em seguida, compilar e executá-lo sem interrupções. Veja um resumo das etapas do upgrade de um app:
- Adicionar as bibliotecas da versão 9 e as bibliotecas de compatibilidade ao app.
- Atualizar as instruções de importação no seu código para compatibilidade com a v9.
- Refatorar o código de um único produto (por exemplo, o Authentication) para o estilo modular.
- Opcional: remover a biblioteca e o código de compatibilidade do Authentication para reduzir o tamanho do app antes de continuar.
- Refatorar funções para cada produto (por exemplo, Cloud Firestore, FCM etc.) para o estilo modular, compilar e testar até que todas as áreas estejam concluídas.
- Atualizar o código de inicialização para o estilo modular.
- Remover do app todos os códigos e instruções de compatibilidade restantes referentes à versão 9.
Obter o SDK da versão 9
Para começar, use o npm para obter as bibliotecas da versão 9 e as de compatibilidade:
npm i firebase@9.22.1 # OR yarn add firebase@9.22.1
Atualizar importações para serem compatíveis com a v9
Para que seu código continue funcionando depois de atualizar a dependência da v8 para a v9 Beta, altere as instruções de importação para usar a versão "compat" de cada importação. Exemplo:
Antes: versão 8
import firebase from 'firebase/app';
import 'firebase/auth';
import 'firebase/firestore';
Depois: compatibilidade com a versão 9
// v9 compat packages are API compatible with v8 code
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
import 'firebase/compat/firestore';
Refatorar para o estilo modular
As APIs da versão 8 são baseadas em um namespace e padrão de serviço encadeados por pontos.
Já com a abordagem modular da versão 9, seu código será
organizado principalmente em torno de funções. Na versão 9, o pacote firebase/app e
outros pacotes não retornam uma exportação abrangente que contém todos os
métodos do pacote. Os pacotes exportam funções individuais.
Na versão 9, os serviços são transmitidos como o primeiro argumento e, em seguida, a função usa os detalhes do serviço para fazer o resto. Vejamos dois exemplos de como isso funciona. Neles, as chamadas para as APIs do Authentication e do Cloud Firestore são refatoradas.
Exemplo 1: refatoração de uma função do Authentication
Antes: compatibilidade com a versão 9
O código de compatibilidade da versão 9 é idêntico ao código da versão 8, mas as importações foram alteradas.
import firebase from "firebase/compat/app";
import "firebase/compat/auth";
const auth = firebase.auth();
auth.onAuthStateChanged(user => {
// Check for user status
});
Depois: modular da versão 9
A função getAuth usa firebaseApp como seu primeiro parâmetro.
A função
onAuthStateChanged não é encadeada na instância auth como seria
na versão 8. Nesta versão, ela é uma função
livre que usa auth como o primeiro parâmetro.
import { getAuth, onAuthStateChanged } from "firebase/auth";
const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
// Check for user status
});
Atualização do tratamento do método getRedirectResult do Auth
A versão 9 apresenta uma alteração interruptiva em getRedirectResult. Quando nenhuma operação de redirecionamento for chamada, a versão 9 vai retornar null, em vez da versão 8, que retornou um UserCredential com um usuário null.
Antes: compatibilidade com a versão 9
const result = await auth.getRedirectResult()
if (result.user === null && result.credential === null) {
return null;
}
return result;
Depois: modular da versão 9
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;
Exemplo 2: refatoração de uma função do Cloud Firestore
Antes: compatibilidade com a versão 9
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);
});
Depois: modular da versão 9
A função getFirestore usa firebaseApp como o primeiro parâmetro, que
foi retornado de initializeApp em um exemplo anterior. Observe como o
código para formar uma consulta é muito diferente na versão 9. Não há encadeamentos e
os métodos como query ou where agora ficam expostos como funções livres.
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());
});
Atualizar as referências para a propriedade DocumentSnapshot.exists do Firestore
A versão 9 apresenta uma alteração interruptiva. A propriedade
firestore.DocumentSnapshot.exists mudou para um método. A
funcionalidade é essencialmente a mesma (verificar se um documento existe),
mas é necessário refatorar seu código para usar o método da v9 conforme mostrado:
Antes: compatibilidade com a versão 9
if (snapshot.exists) {
console.log("the document exists");
}
Depois: modular da versão 9
if (snapshot.exists()) {
console.log("the document exists");
}
Exemplo 3: combinação dos estilos de código das versões 8 e 9
O uso das bibliotecas de compatibilidade durante o upgrade permite que você continue usando o código da versão 8 com o código refatorado para a versão 9. Isso significa que é possível manter o código da versão 8 para o Cloud Firestore enquanto refatora o código do Authentication ou de outro SDK do Firebase para o estilo da versão 9 e ainda compilar o app com os dois estilos de código. O mesmo vale para o código das versões 8 e 9 em um produto como o Cloud Firestore. Estilos de código novos e antigos podem coexistir, desde que você importe os pacotes de compatibilidade:
import firebase from 'firebase/compat/app';
import 'firebase/compat/firestore';
import { getDoc } from 'firebase/firestore'
const docRef = firebase.firestore().doc();
getDoc(docRef);
Embora seu app faça a compilação, você não terá acesso aos benefícios do tamanho do app do código modular até que remova todas as instruções e o código de compatibilidade do app.
Atualizar código de inicialização
Atualize o código de inicialização do app para usar a nova sintaxe da versão 9 modular. É
importante atualizar esse código depois de concluir a refatoração de todo o
código no app, porque firebase.initializeApp() inicializa o estado
global das APIs modulares e de compatibilidade, enquanto a função
initializeApp() modular inicializa somente o estado para modular.
Antes: compatibilidade com a versão 9
import firebase from "firebase/compat/app"
firebase.initializeApp({ /* config */ });
Depois: modular da versão 9
import { initializeApp } from "firebase/app"
const firebaseApp = initializeApp({ /* config */ });
Remover código de compatibilidade
Para saber os benefícios de tamanho do SDK modular da versão 9, você precisa
converter todas as invocações para o estilo modular mostrado acima e remover todas as
instruções import "firebase/compat/* do código. Quando terminar, não
haverá mais referências ao namespace global firebase.* nem a qualquer outro
código no estilo do SDK da versão 8.
Como usar a biblioteca de compatibilidade pela janela
O SDK da versão 9 é otimizado para funcionar com módulos em vez do objeto
window do navegador. As versões anteriores da biblioteca permitiam o carregamento e o gerenciamento do Firebase usando o namespace window.firebase. Isso não é
recomendado a partir de agora, porque não permite a eliminação de códigos não utilizados.
No entanto, a versão de compatibilidade do SDK para JavaScript funciona com o window
para desenvolvedores que preferem não iniciar imediatamente o caminho de upgrade modular.
<script src="https://www.gstatic.com/firebasejs/9.22.1/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.22.1/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.22.1/firebase-auth-compat.js"></script>
<script>
const firebaseApp = firebase.initializeApp({ /* Firebase config */ });
const db = firebaseApp.firestore();
const auth = firebaseApp.auth();
</script>
A biblioteca de compatibilidade usa o código modular da versão 9 em segundo plano e o fornece com a mesma API que o SDK da versão 8. Isso significa que é possível consultar a referência da API da versão 8 e os snippets de código da versão 8 para mais detalhes. Esse método não é recomendado para uso a longo prazo, mas como início para fazer upgrade para a biblioteca totalmente modular da versão 9.
Benefícios e limitações da versão 9
A versão 9 totalmente modular tem as seguintes vantagens em relação às versões anteriores:
- A versão 9 oferece um tamanho de app significativamente reduzido. Ela adota o formato moderno do módulo JavaScript, permitindo práticas "tree shaking" em que você importa apenas os artefatos que são necessários para o app. Dependendo do seu app, o "tree shaking" com a versão 9 pode resultar em 80% menos kilobytes do que um app comparável criado com a versão 8.
- A versão 9 continuará se beneficiando do desenvolvimento contínuo de recursos, enquanto a versão 8 será congelada futuramente.