Atualize para o SDK para a Web modular (v9)

As apps que usam atualmente a versão 8 ou anterior do SDK Web devem considerar a migração para a versão 9 seguindo as instruções neste guia.

Este guia pressupõe que está familiarizado com a versão 8 e que vai tirar partido de um agrupador de módulos, como o webpack ou o Rollup, para a atualização e o desenvolvimento contínuo da versão 9.

Recomendamos vivamente a utilização de um agrupador de módulos no seu ambiente de desenvolvimento. Se não usar um, não poderá tirar partido das principais vantagens da versão 9, que incluem a redução do tamanho da app. Precisa do npm ou do yarn para instalar o SDK.

Acerca das bibliotecas de compatibilidade

Existem dois tipos de bibliotecas disponíveis para a versão 9 do SDK Web:

  • Modular: uma nova superfície da API concebida para facilitar a eliminação de código não utilizado, de modo a tornar a sua app Web o mais pequena e rápida possível.
  • Compat: uma superfície de API familiar totalmente compatível com a versão 8, que lhe permite atualizar para a versão 9 sem alterar todo o código do SDK de uma só vez. As bibliotecas de compatibilidade têm poucas ou nenhumas vantagens de tamanho ou desempenho em relação às respetivas contrapartes da versão 8.

Este guia pressupõe que vai tirar partido das bibliotecas de compatibilidade da versão 9 para facilitar a atualização. Estas bibliotecas permitem-lhe continuar a usar o código da versão 8 juntamente com o código refatorado para a versão 9. Isto significa que pode compilar e depurar a sua app mais facilmente à medida que avança no processo de atualização.

Para apps com uma exposição muito pequena ao SDK Web, pode ser prático refatorar o código da versão 8 sem usar as bibliotecas de compatibilidade da versão 9. Se estiver a atualizar uma app deste tipo, pode seguir as instruções neste guia para a "versão 9 modular" sem usar as bibliotecas de compatibilidade.

Acerca do processo de atualização

Cada passo do processo de atualização tem um âmbito definido para que possa terminar de editar o código fonte da sua app e, em seguida, compilá-lo e executá-lo sem falhas. Em resumo, veja o que tem de fazer para atualizar uma app:

  1. Adicione as bibliotecas da versão 9 e as bibliotecas de compatibilidade à sua app.
  2. Atualize as declarações de importação no seu código para a compatibilidade com a v9.
  3. Refatore o código para o estilo modular.
  4. Remova a biblioteca de compatibilidade de autenticação e o código de compatibilidade para a autenticação de modo a usufruir da vantagem do tamanho da app.
  5. Atualize o código de inicialização para o estilo modular.
  6. Remova todas as declarações de compatibilidade e o código de compatibilidade da versão 9 restantes da sua app.

Obtenha o SDK versão 9

Para começar, obtenha as bibliotecas da versão 9 e as bibliotecas de compatibilidade através do npm (versão mais recente https://www.npmjs.com/package/firebase):

npm i firebase@12.4.0

# OR

yarn add firebase@12.4.0

Atualize as importações para a compatibilidade com a v9

Para manter o código a funcionar após a atualização da dependência da versão 8 para a versão 9, altere as declarações de importação para usar a versão "compat" de cada importação. Por 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';

Refatore para o estilo modular

Embora as APIs da versão 8 se baseiem num espaço de nomes com encadeamento de pontos e num padrão de serviço, a abordagem modular da versão 9 significa que o seu código será organizado principalmente em torno de funções. Na versão 9, o pacote firebase/app e outros pacotes não devolvem uma exportação abrangente que contenha todos os métodos do pacote. Em vez disso, 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 de autenticação simples

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. A utilização das bibliotecas de compatibilidade durante a atualização permite-lhe continuar a usar o código da versão 8 juntamente 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: versão modular 9

A função getAuth usa firebaseApp como primeiro parâmetro. A função onAuthStateChanged não está encadeada a partir da instância de autenticação, como estaria 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
});

Atualize o código de inicialização

Atualize o código de inicialização da sua app para usar a nova sintaxe modular da versão 9. É importante atualizar este código depois de concluir a refatoração de todo o código na sua app. Isto deve-se ao facto de firebase.initializeApp() inicializar o estado global para as APIs compatíveis e modulares, enquanto a função modular initializeApp() inicializa apenas o estado para modular.

Antes: compatibilidade com a versão 9

import firebase from "firebase/compat/app"

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

Depois: versão modular 9

import { initializeApp } from "firebase/app"

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

Remova o código de compatibilidade

Para usufruir das vantagens de tamanho do SDK modular da versão 9, deve, eventualmente, converter todas as invocações para o estilo modular apresentado acima e remover todas as declarações import "firebase/compat/* do seu código. Quando terminar, não deve haver mais referências ao espaço de nomes global firebase.* nem a qualquer outro código no estilo do SDK versão 8.

Vantagens e limitações da versão 9

A versão 9 totalmente modularizada tem as seguintes vantagens em relação às versões anteriores:

  • A versão 9 permite um tamanho da app significativamente reduzido. Adota o formato de módulo JavaScript moderno, o que permite práticas de "tree shaking" nas quais importa apenas os artefactos de que a sua app precisa. Consoante a sua app, a remoção de código não utilizado com a versão 9 pode resultar numa redução de 80% dos quilobytes em comparação com uma app comparável criada com a versão 8.
  • A versão 9 vai continuar a beneficiar do desenvolvimento contínuo de funcionalidades, enquanto a versão 8 vai ser congelada num ponto no futuro.