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.

Este guia presume que você já conhece a versão 8 e que vai usar um bundler de módulos, como webpack ou Rollup (links em inglês), para atualização e desenvolvimento contínuo da versão 9.

É altamente recomendável usar um bundler de módulos 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ê 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) e deixar 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 vez. As bibliotecas de compatibilidade têm pouca ou nenhuma vantagem de tamanho ou desempenho em relação às versões 8 compatíveis.

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 é possível 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 da "versão 9 modular" do guia 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 do 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, instale as bibliotecas da versão 9 e de compatibilidade usando o npm (versão mais recente https://www.npmjs.com/package/firebase):

npm i firebase@10.11.1

# OR

yarn add firebase@10.11.1

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

Para manter o código funcionando depois de atualizar a dependência da v8 para a v9, altere as instruções de importação para usar a versão de compatibilidade 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 dele. 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 "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 vai continuar a se beneficiar do desenvolvimento contínuo de recursos, enquanto a versão 8 será congelada no futuro.