Actualiza a la versión 10 del SDK de Admin para Node.js (SDK modular)

La versión 10 del SDK de Admin para Node.js incluye dos cambios importantes:

  • Se descontinuó la compatibilidad con Node.js 10 (este es un cambio rotundo).
  • El SDK adoptó un patrón modular de API.

En esta guía, se proporcionan instrucciones y también información para ayudar a los desarrolladores a actualizar las apps de Node.js existentes de versiones anteriores del SDK de Admin a la versión 10.

Actualiza Node.js a la versión 12 o posterior

Con la actualización de la versión 10 del SDK de Admin para Node.js, se descontinuó la compatibilidad de Firebase con Node.js 10. Los desarrolladores deben utilizar Node.js 12 o versiones posteriores cuando usen el SDK de Admin. Si usas el SDK de Admin para Node.js junto con Cloud Functions para Firebase, asegúrate de haber actualizado tu versión de Node.js a la versión 12 o posterior.

Usa módulos en lugar de espacios de nombres

Desde su inicio, el SDK de Admin para Node.js ha ofrecido una API estable estructurada como jerarquía de espacio de nombres anidada. Como resultado, podrías estar familiarizado con la escritura de código similar al siguiente:

// 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 de la versión 10, el SDK de Admin para Node.js ofrece varios puntos de entrada modulares con exportaciones con nombre. Recomendamos a los desarrolladores usar estos nuevos puntos de entrada para acceder a las diferentes API del SDK, en lugar de usar el espacio de nombres admin global.

Así se vería el ejemplo anterior con los nuevos puntos de entrada modulares:

TypeScript

// 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');

Node.js

// 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');

Uso de puntos de entrada modulares de la versión 10

Ten en cuenta que, en los ejemplos anteriores, ya no importas un espacio de nombres admin global. En su lugar, importas de manera explícita solamente los símbolos que necesitas desde varios puntos de entrada modulares. Además, los desarrolladores de TypeScript ya no tienen que usar identificadores de tipo triple anidado como admin.auth.UserRecord y admin.database.Reference. Debido a que cada tipo pertenece exactamente a un módulo, puedes importarlos por sus nombres cortos, como UserRecord y Reference.

Estos son todos los puntos de entrada modulares disponibles en el SDK a partir de la versión 10:

  • 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

En la siguiente tabla, se muestra la sintaxis de importación que reemplaza cada una de las funciones de espacio de nombres heredadas:

v9 v10
admin.initializeApp() import { initializeApp } from 'firebase-admin/app'

initializeApp();

admin.app() import { getApp } from 'firebase-admin/ap'

getApp();

admin.credential.cert() import { cert } from 'firebase-admin/app'

cert();

admin.auth() import { getAuth } from 'firebase-admin/auth'

getAuth();

admin.database() import { getDatabase } from 'firebase-admin/database'

getDatabase();

admin.firestore() import { getFirestore } from 'firebase-admin/firestore'

getFirestore();

admin.instanceId() import { getInstanceId } from 'firebase-admin/instance-id'

getInstanceId();

admin.machineLearning() import { getMachineLearning } from 'firebase-admin/machine-learning'

getMachineLearning();

admin.messaging() import { getMessaging } from 'firebase-admin/messaging'

getMessaging()

admin.projectManagement() import { getProjectManagement } from 'firebase-admin/project-management'

getProjectManagement();

admin.remoteConfig() import { getRemoteConfig } from 'firebase-admin/remote-config'

getRemoteConfig();

admin.securityRules() import { getSecurityRules } from 'firebase-admin/security-rules'

getSecurityRules()

admin.storage() import { getStorage } from 'firebase-admin/storage'

getStorage();

Usa funciones exportadas en lugar de métodos en apps

En la API heredada, el objeto App exponía varios métodos, como app.auth() y app.database(). Recomendamos que, en lugar de esos métodos, los desarrolladores usen los mismos puntos de entrada modulares que se describieron anteriormente a fin de obtener instancias de servicio acotadas a un objeto App determinado y realizar otras tareas específicas de la app.

v9 v10
app.auth() import { getAuth } from 'firebase-admin/auth';

getAuth(app);

app.database() import { getDatabase } from 'firebase-admin/database';

getDatabase(app);

app.database(url) import { getDatabaseWithUrl } from 'firebase-admin/database';

getDatabaseWithUrl(url, app);

app.firestore() import { getFirestore } from 'firebase-admin/firestore'

getFirestore(app);

app.instanceId() import { getInstanceId } from 'firebase-admin/instance-id'

getInstanceId(app);

app.machineLearning() import { getMachineLearning } from 'firebase-admin/machine-learning'

getMachineLearning(app);

app.messaging() import { getMessaging } from 'firebase-admin/messaging'

getMessaging(app);

app.projectManagement() import { getProjectManagement } from 'firebase-admin/project-management'

getProjectManagement(app);

app.remoteConfig() import { getRemoteConfig } from 'firebase-admin/remote-config'

getRemoteConfig(app);

app.securityRules() import { getSecurityRules } from 'firebase-admin/security-rules'

getSecurityRules(app);

app.storage() import { getStorage } from 'firebase-admin/storage'

getStorage(app);

app.delete() import { deleteApp } from 'firebase-admin/app';

deleteApp(app);

Compatibilidad con módulos de ES

Node.js 12 y las versiones posteriores incluyen compatibilidad experimental con los módulos de ES, lo que permite que incluso los desarrolladores que no usan TypeScript utilicen las palabras clave export y import en su código. A partir de la versión 10, el SDK de Admin para Node.js también ofrece compatibilidad con los módulos de ES, de modo que los desarrolladores que implementen estos módulos en Node.js llano puedan importar el SDK mediante la sintaxis import.

Para usar módulos de ES con el SDK de Admin, primero asegúrate de habilitar la compatibilidad con ESM en tu entorno de ejecución Node.js. Para ello, se suele agregar un campo "type": "module" al archivo package.json. Luego, puedes escribir código como el siguiente para la aplicación:

// 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');