Fazer upgrade para o SDK Admin v10 do SDK para Node.js (SDK modular)

A versão 10 do SDK Admin para Node.js apresenta duas mudanças importantes:

• O suporte ao Node.js 10 foi interrompido. Essa é uma alteração interruptiva.
• O SDK adotou um padrão de API modular

Neste guia, fornecemos instruções e informações para ajudar os desenvolvedores a fazer upgrade para a v10 em apps Node.js que usam as versões anteriores do SDK Admin.

Atualizar o Node.js para a v12 ou mais recente

Com a versão v10 do SDK Admin para Node.js, o Firebase suspendeu o suporte para o Node.js 10. Ao usar o SDK Admin, Os desenvolvedores precisam usar o Node.js 12 ou versões posteriores. Se você estiver usando o SDK Admin para Node.js com o Cloud Functions para Firebase, faça upgrade da sua versão do Node.js para a 12 ou uma versão mais recente.

Usar módulos em vez de namespaces

Desde a criação, o SDK Admin para Node.js oferece uma API estável e estruturada como uma hierarquia de namespaces aninhada. Por isso, talvez você já conheça a escrita de um código como este:

// Import the global admin namespace
import * as admin from 'firebase-admin';

const app: admin.app.App = admin.initializeApp();

const token: string = await admin.auth().createCustomToken('alice');

const user: admin.auth.UserRecord = await admin.auth().getUser('bob');

A partir da v10, o SDK Admin para Node.js oferece vários pontos de entrada de módulos com exportações nomeadas. Recomendamos que os desenvolvedores usem esses novos pontos de entrada para acessar as várias APIs do SDK, em vez de usar o namespace admin global.

Veja como seria o exemplo acima com os pontos de entrada do novo módulo:

// Import only what you need
import { initializeApp, App } from 'firebase-admin/app';
import { getAuth, UserRecord } from 'firebase-admin/auth';

const app: App = initializeApp();

const token: string = await getAuth().createCustomToken('alice');

const user: UserRecord = getAuth().getUser('bob');

// Import only what you need
const { initializeApp } = require('firebase-admin/app');
const { getAuth } = require('firebase-admin/auth');

const app = initializeApp();

const token = await getAuth().createCustomToken('alice');

const user = getAuth().getUser('bob');

Como usar pontos de entrada modulares v10

Nos exemplos acima, você não importa mais um namespace admin global. Em vez disso, você importa explicitamente apenas os símbolos necessários de vários pontos de entrada do módulo. Além disso, desenvolvedores do TypeScript não precisam mais usar identificadores de tipos aninhados três vezes, como admin.auth.UserRecord e admin.database.Reference. Como cada tipo pertence exatamente a um módulo, é possível importá-los pelos nomes curtos, como UserRecord e Reference.

Veja todos os pontos de entrada do módulo disponíveis no SDK a partir da v10:

• firebase-admin/app
• firebase-admin/auth
• firebase-admin/database
• firebase-admin/firestore
• firebase-admin/instance-id
• firebase-admin/machine-learning
• firebase-admin/messaging
• firebase-admin/project-management
• firebase-admin/remote-config
• firebase-admin/security-rules
• firebase-admin/storage

Veja na tabela a seguir a sintaxe de importação de substituição para cada uma das funções de namespace legadas:

Usar funções exportadas em vez de métodos no app

Na API legada, o objeto App expôs vários métodos como app.auth() e app.database(). Recomendamos que desenvolvedores evitem usar esses métodos. Em vez disso, use os mesmos pontos de entrada de módulo descritos acima para acessar instâncias de serviço com escopo definido para um determinado objeto App e realizar outras tarefas específicas do app.

Compatibilidade com módulos ES

O Node.js 12 e versões posteriores oferecem suporte experimental com módulos ES, permitindo que até mesmo desenvolvedores que não utilizam TypeScript usem as palavras-chave export e import no código. A partir da versão v10, o SDK Admin para Node.js também oferece suporte a módulos ES, de modo que os desenvolvedores que implementam módulos ES na linguagem Node.js simples podem importar o SDK usando a sintaxe import.

Para usar módulos ES com o SDK Admin, primeiro ative o suporte do ESM para o ambiente de execução do Node.js. Normalmente, isso é feito adicionando um campo "type": "module" ao seu arquivo package.json. Em seguida, escreva o código do aplicativo da seguinte maneira:

// With {type: module} in the package.json...

// Import only what you need
import { initializeApp }  from 'firebase-admin/app';
import { getAuth } from 'firebase-admin/auth';

const app = initializeApp();

const token = await getAuth().createCustomToken('alice');

const user = getAuth().getUser('bob');