Fazer upgrade para o SDK modular da Web (v9)

Os apps que atualmente usam o SDK da Web versão 8 ou anterior precisam migrar para a versão 9 usando as instruções deste guia.

Para seguir este guia, é necessário ter familiaridade com a versão 8 e que você vai usar um bundler de módulo, como webpack ou Rollup (links em inglês), para upgrade e desenvolvimento contínuo da versão 9.

É altamente recomendável usar um bundler de módulos no ambiente de desenvolvimento. Se você não usar um, não poderá aproveitar os principais benefícios da versão 9 no tamanho do app reduzido. Você vai precisar de npm ou yarn para instalar o SDK.

Sobre as bibliotecas de compatibilidade

Há dois tipos de bibliotecas disponíveis para o SDK da Web versão 9:

  • Modular: uma nova plataforma de API criada para facilitar o tree shaking (remoção de código não utilizado), o que torna seu app da Web menor e o mais rápido possível.
  • Compatibilidade: uma plataforma de API conhecida que é totalmente compatível com a versão 8, permitindo que você faça upgrade para a versão 9 sem mudar todo o código do SDK de uma só vez. As bibliotecas de compatibilidade têm poucas ou nenhuma vantagem de tamanho ou desempenho em relação às versões 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.

Para apps com uma exposição muito pequena ao SDK da Web, 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 deste 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:

  1. Adicionar as bibliotecas da versão 9 e as bibliotecas de compatibilidade ao app.
  2. Atualizar as instruções de importação no seu código para compatibilidade com a v9.
  3. Refatorar o código para o estilo modular.
  4. Remova a biblioteca e o código de compatibilidade do Authentication para aproveitar o benefício no tamanho do app.
  5. Atualizar o código de inicialização para o estilo modular.
  6. 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, faça o download das bibliotecas da versão 9 e das de compatibilidade usando o npm (versão mais recente https://www.npmjs.com/package/firebase):

npm i firebase@10.12.2

# OR

yarn add firebase@10.12.2

Atualizar importações para serem compatíveis com a v9

Para que o código continue funcionando depois de atualizar a dependência da v8 para a v9, altere as instruções de importação para usar a versão "compatível" 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.

Exemplo: refatoração de uma função simples 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. 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.

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 de autenticação como seria na versão 8. Em vez disso, é 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
});

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.

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. Ele adota o formato moderno de módulo JavaScript, permitindo práticas de tree shaking em que você importa apenas os artefatos 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á a se beneficiar do desenvolvimento contínuo de recursos, enquanto a versão 8 será congelada futuramente.