Firebase Cloud Functions — qué es, desencadenadores y cómo escribir funciones

Qué son Firebase Cloud Functions y cómo funcionan

Firebase Cloud Functions es una plataforma de computación construida sobre Google Cloud Functions (GCF), adaptada para el ecosistema de Firebase. Las funciones son código JavaScript o TypeScript normal exportado desde un módulo y registrado para un tipo de evento específico. Cuando ocurre un evento (por ejemplo, un usuario se registra o sube un archivo), Firebase Cloud Functions ejecuta el código correspondiente, pasándole el contexto del evento.

La arquitectura de Cloud Functions sigue el principio de responsabilidad única: una función maneja un tipo de evento y realiza una operación atómica. Por ejemplo, la función sendWelcomeEmail se activa cuando se crea un nuevo usuario en Firebase Authentication y envía un correo de bienvenida. Este aislamiento simplifica la depuración, las pruebas y la reutilización de funciones en diferentes proyectos.

Cada función se ejecuta en un contenedor aislado con un ciclo de vida temporal. El tiempo máximo de ejecución por defecto es de 60 segundos (funciones HTTPS — 9 minutos). Si una función no completa su ejecución dentro del tiempo de espera, la solicitud falla con error 500. Para operaciones de larga duración, use Cloud Tasks o Pub/Sub con reintentos. Los contenedores pueden reutilizarse para llamadas posteriores (keep-alive), lo que reduce la latencia en arranques en frío después de la primera llamada.

Entorno de ejecución y versiones de Node.js

Firebase Cloud Functions admite varias versiones de Node.js: 18, 20 y 22 (recomendada para nuevos proyectos). La versión se especifica en el campo engines del archivo package.json. Firebase CLI configura automáticamente el entorno de ejecución según la versión especificada. Es importante destacar que Firebase Cloud Functions no admite la ejecución de contenedores Docker arbitrarios — el entorno está estrictamente fijado por Google Cloud Functions.

Para proyectos nuevos, se recomienda Node.js 22, ya que incluye las últimas optimizaciones de V8, mejor soporte para módulos ESM y soporte WebSocket a nivel de plataforma. Si un proyecto utiliza dependencias compiladas para una versión específica de Node (por ejemplo, módulos nativos en C++), la compatibilidad debe verificarse individualmente — no todos los módulos nativos se compilan en el entorno GCF.

Diferencia entre Firebase Cloud Functions y Google Cloud Functions

Firebase Cloud Functions es una envoltura sobre Google Cloud Functions con Firebase SDK preinstalado e integración con los servicios de Firebase. El desarrollador escribe código utilizando el SDK firebase-functions, que proporciona desencadenadores tipados para todos los servicios de Firebase. Google Cloud Functions es una plataforma de nivel inferior donde los desencadenadores se configuran explícitamente a través de Eventarc o Pub/Sub.

La diferencia clave: en Firebase Cloud Functions, un desencadenador se registra declarativamente mediante functions.firestore.document('path').onWrite(), mientras que en Google Cloud Functions se configura a través de Eventarc con filtrado de atributos de evento. Firebase Cloud Functions también incluye el Admin SDK inicializado automáticamente con las credenciales de la cuenta de servicio del proyecto, proporcionando acceso completo a todos los servicios de Firebase sin configuración adicional.

Tipos de desencadenadores: qué eventos se admiten

Firebase Cloud Functions admite 8 categorías de desencadenadores, cada una correspondiente a un servicio específico de Firebase o Google Cloud. Un desencadenador es una condición que, al cumplirse, invoca automáticamente una función. El desarrollador no gestiona el ciclo de vida de la función directamente: Firebase CLI registra el desencadenador en Google Cloud Eventarc, y la plataforma en la nube ejecuta la función cuando ocurre el evento.

Los desencadenadores más populares son los de Firestore: onWrite, onCreate, onUpdate, onDelete. Se activan cuando cambian documentos en las colecciones de Firestore. La función recibe instantáneas del documento antes y después del cambio, lo que permite comparar valores y reaccionar solo a cambios específicos. Por ejemplo, cuando el estado de un pedido cambia de “pending” a “shipped”, se puede enviar una notificación push al usuario.

Los desencadenadores de Authentication (onCreate, onDelete) se activan cuando se crea o elimina una cuenta de usuario. Se utilizan para inicializar datos de usuario: crear un documento de usuario en Firestore, enviar un correo de bienvenida, escribir en analytics. Nota: la función no puede cancelar la creación del usuario — se ejecuta después de que la cuenta ya está creada. Para prevalidación, use las Blocking Functions disponibles en Identity Platform.

Desencadenadores HTTPS y CORS

Las funciones HTTPS (onRequest) permiten crear endpoints de API REST completos accesibles mediante HTTP. A diferencia de los desencadenadores basados en eventos, las funciones HTTPS se invocan a través de una URL de la forma https://{region}-{project}.cloudfunctions.net/{functionName}. Es importante configurar CORS correctamente si el endpoint se llama desde un navegador o una aplicación móvil. Firebase SDK no incluye cabeceras CORS automáticamente — deben añadirse manualmente mediante middleware.

Para clientes móviles (Android, iOS), CORS no es necesario ya que los clientes HTTP nativos no están restringidos por la política de Cross-Origin. CORS solo es relevante para peticiones web. Si su función HTTPS se llama tanto desde la aplicación como desde la web, añada un manejo CORS universal: res.set('Access-Control-Allow-Origin', '*') para desarrollo o una lista de dominios permitidos para producción.

Programación con Pub/Sub y Cloud Scheduler

Para la ejecución periódica (tareas cron), use una combinación de Cloud Scheduler y Pub/Sub. Cloud Scheduler envía un mensaje a un tema de Pub/Sub según un horario, y el desencadenador onPublish de Cloud Functions procesa ese mensaje. Firebase CLI no admite sintaxis cron directa — el horario se configura mediante la consola de Google Cloud o Terraform en formato unix-cron: 0 3 * * * (todos los días a las 3:00).

Ejemplos de tareas: boletín diario, limpieza de datos obsoletos, generación de informes, sincronización con APIs externas. Importante: Cloud Scheduler es un servicio de pago de Google Cloud (alrededor de $2 al mes por trabajo). Cada activación cuenta como una llamada de función separada y se factura según las tarifas estándar de Cloud Functions.

Cómo escribir y desplegar funciones

El desarrollo de Cloud Functions comienza iniciando un proyecto mediante Firebase CLI: firebase init functions. Este comando crea un directorio functions/ con una plantilla index.js (o index.ts), un archivo package.json y configuración de TypeScript (si se selecciona). Tras la inicialización, simplemente escriba una función, expórtela desde el módulo y ejecute firebase deploy --only functions para desplegarla.

Cada función se registra llamando al método de desencadenador correspondiente. Ejemplo de una función HTTPS: exports.helloWorld = functions.https.onRequest((req, res) => { res.send(“Hello!”); }). Firebase Functions utiliza un modelo asíncrono: para desencadenadores basados en eventos (no HTTPS), la función debe devolver una Promise. Firebase espera a que la Promise se complete antes de terminar el contenedor. Si no se devuelve una Promise, la función puede terminarse antes de que finalicen las operaciones asíncronas.

El desarrollo local se realiza a través de Firebase Emulator Suite, que incluye un emulador de Cloud Functions. El comando firebase emulators:start inicia un servidor local con funciones accesibles en http://localhost:5001. El emulador admite recarga en caliente cuando el código cambia y está completamente aislado del entorno de producción, permitiendo pruebas sin riesgo para datos reales.

Gestión de dependencias y configuración

Las dependencias de Cloud Functions se gestionan mediante package.json. Firebase instala solo las dependencias de producción (dependencies, no devDependencies). El tamaño del paquete de funciones afecta el tiempo de arranque en frío: se recomienda minimizar el número de dependencias. La dependencia firebase-admin está preinstalada para Firebase Admin SDK — no es necesario añadirla manualmente.

Los datos confidenciales (claves API, tokens) no deben almacenarse en el código de la función. Use functions.config() para almacenar configuración: firebase functions:config:set stripe.key=“sk_...”. Los valores se cifran y están disponibles en tiempo de ejecución mediante functions.config().stripe.key. Para configuraciones serializadas grandes, use Google Cloud Secret Manager.

Manejo de errores y registro

El registro en Cloud Functions se realiza mediante console.log, console.warn y console.error. Todos los registros se recogen automáticamente en Google Cloud Logging y están disponibles en la consola de Firebase (Functions > Logs). Para registro estructurado, use las bibliotecas winston o pino, que admiten formato JSON y niveles de registro.

El manejo de errores es crítico para la fiabilidad: una excepción no capturada en una Promise termina la función con un error, tras lo cual Firebase reintenta automáticamente con retroceso exponencial. El número de reintentos es configurable: de 0 a infinito. Para desencadenadores basados en eventos, se recomienda activar los reintentos para garantizar que cada evento se procese incluso durante fallos temporales de servicios externos.

Arranque en frío y escalabilidad

El arranque en frío (cold start) es la demora en la primera invocación de una función tras un período de inactividad, cuando el contenedor con el código se carga e inicializa de nuevo. Según la documentación de Firebase (2026), un arranque en frío tarda de 200 ms a 2 segundos dependiendo del tamaño del paquete, el número de dependencias y la región. Para la interfaz de usuario, una demora superior a 1 segundo es notable y puede afectar la experiencia del usuario.

Formas de minimizar el arranque en frío: minimizar dependencias, usar TypeScript compilado a CommonJS, reducir el tamaño del paquete de funciones, establecer un número mínimo de instancias activas. Firebase Cloud Functions v2 (2.ª generación) permite configurar minInstances — el número mínimo de contenedores calientes siempre listos para procesar solicitudes. Mantener contenedores calientes genera cargos por tiempo de inactividad.

La escalabilidad de Cloud Functions ocurre automáticamente: al aumentar el volumen de solicitudes, Firebase crea nuevos contenedores. Por defecto, el número máximo de instancias paralelas es 3000 (cuota del proyecto de Google Cloud). Cada instancia maneja una solicitud a la vez. Si una función es rápida (menos de 100 ms), una instancia puede manejar hasta 10 solicitudes por segundo, proporcionando un rendimiento máximo de hasta 30 000 solicitudes por segundo por proyecto.

Configuración de minInstances y maxInstances

minInstances es un parámetro que reserva un número específico de contenedores y los mantiene calientes. Se recomienda para funciones HTTPS críticas donde la latencia de arranque en frío es inaceptable. Por ejemplo, para un endpoint de autenticación, configure minInstances: 1. maxInstances limita el número máximo de instancias paralelas, útil para prevenir un crecimiento descontrolado de costos durante picos repentinos de tráfico.

La configuración se realiza en el código: functions.runWith({ minInstances: 1, maxInstances: 10 }). Importante: minInstances aumenta el costo porque los contenedores se ejecutan continuamente. Para proyectos de prueba, minInstances debe desactivarse. Para producción, se recomienda minInstances para todas las funciones HTTPS públicas y 0 para desencadenadores basados en eventos donde una demora de 1 segundo no es crítica.

Regiones de despliegue

La región de despliegue afecta la latencia hacia los usuarios finales y el costo del tráfico saliente. Firebase Cloud Functions está disponible en más de 30 regiones de Google Cloud. Para aplicaciones móviles, elija la región más cercana a su audiencia objetivo: us-central1 para América, europe-west1 para Europa, asia-east2 para Asia. La región no se puede cambiar después del despliegue sin redeployar la función.

El cambio de región se realiza mediante el parámetro region en el código: functions.region('europe-west1'). Todas las funciones en un mismo archivo pueden tener diferentes regiones. Para proyectos globales, se recomienda desplegar funciones en múltiples regiones y usar Cloud Load Balancing para distribuir el tráfico, aunque para la mayoría de las aplicaciones móviles una sola región es suficiente si se elige correctamente.

Ejemplos de código para Firebase Cloud Functions

Veamos ejemplos prácticos de Cloud Functions en TypeScript. El código utiliza Firebase Functions SDK v2 (2.ª generación) con sintaxis de módulos ES. Los ejemplos incluyen el manejo de un evento de creación de usuario, la generación de una miniatura al subir una imagen y un endpoint HTTPS simple para una API REST. Todas las funciones son asíncronas y devuelven una Promise para la terminación correcta del contenedor.

Antes de ejecutar, asegúrese de que Firebase CLI esté actualizado a la versión 13+: npm install -g firebase-tools. Las funciones v2 requieren el plan de precios Blaze. Inicialización: firebase init functions con TypeScript seleccionado.

Manejo del registro de usuario

El primer ejemplo — creación de un documento en Firestore cuando un nuevo usuario se registra. La función se activa mediante el evento auth.user().onCreate y escribe un perfil básico en la colección users/{uid}. Esto garantiza que cada usuario registrado tenga un documento con los campos necesarios.

import * as functions from "firebase-functions"
import * as admin from "firebase-admin"

admin.initializeApp()

export const createUserProfile = functions.auth
    .user()
    .onCreate(async (user) => {
        const profile = {
            email: user.email,
            displayName: user.displayName ?? "User",
            createdAt: admin.firestore.Timestamp.now(),
            role: "free",
            avatarUrl: null,
        }

        await admin.firestore()
            .collection("users")
            .doc(user.uid)
            .set(profile)

        console.log(`Profile created for ${user.uid}`)
    })

La función createUserProfile es asíncrona — devuelve una Promise que Firebase espera antes de terminar. Si la escritura en Firestore falla (por ejemplo, debido a permisos insuficientes), la función se reintentará automáticamente (si el reintento está activado). El campo role con valor “free” permite implementar restricciones del nivel gratuito directamente en las Security Rules de Firestore comparando resource.data.role con el nivel de acceso requerido.

Generación de miniaturas al subir imágenes

El segundo ejemplo — un desencadenador de Storage para generar automáticamente una miniatura después de subir una imagen. La función crea una copia reducida de 200x200 píxeles y la guarda en la ruta del archivo original con el prefijo thumb_. El procesamiento de imágenes utiliza la biblioteca sharp, que admite todos los formatos comunes y funciona en el entorno Node.js sin dependencias del sistema.

import * as path from "path"
import * as os from "os"
import * as sharp from "sharp"

export const generateThumbnail = functions.storage
    .object()
    .onFinalize(async (object) => {
        if (!object.contentType?.startsWith("image/")) return

        const filePath = object.name!
        const thumbPath = filePath.replace(
            /(\.\w+)$/, "_thumb$1"
        )

        const bucket = admin.storage().bucket()
        const tempDir = os.tmpdir()
        const tempFile = path.join(tempDir, path.basename(filePath))

        await bucket.file(filePath).download({ destination: tempFile })
        await sharp(tempFile)
            .resize(200, 200, { fit: "cover" })
            .toFile(tempFile.replace(/(\.\w+)$/, "_thumb$1"))

        await bucket.upload(tempFile.replace(
            /(\.\w+)$/, "_thumb$1"
        ), { destination: thumbPath })
    })

La función generateThumbnail verifica el Content-Type del objeto e ignora los que no son imágenes, ahorrando recursos. Para usar sharp, la dependencia debe añadirse a package.json. La miniatura se crea con el parámetro fit: “cover”, que recorta la imagen desde el centro hasta un cuadrado de 200x200 píxeles. Tras la creación, la miniatura se sube de nuevo al mismo bucket con un nombre modificado.

Endpoint HTTPS para una API pública

El tercer ejemplo — una función HTTPS que implementa un endpoint de API REST para verificar el estado del servidor. La función acepta una solicitud GET y devuelve JSON con información sobre el estado de los servicios de Firebase conectados al proyecto. Este endpoint es útil para monitorización y sistemas externos que necesitan verificar la disponibilidad del backend antes de enviar datos.

import * as express from "express"

const app = express.Router()

app.get("/status", async (req, res) => {
    try {
        const db = admin.firestore()
        await db.collection("_health").doc("check").get()
        res.json({ status: "ok", timestamp: Date.now() })
    } catch (error) {
        res.status(503).json({ status: "error", message: error })
    }
})

export const api = functions.https.onRequest(app)

La función api utiliza express Router para el enrutamiento, lo que es conveniente al crear múltiples endpoints en una sola función. La comprobación de salud escribe en Firestore en la colección _health, permitiendo verificar simultáneamente la disponibilidad de Firestore. Para producción, se recomienda añadir autenticación de solicitud mediante una clave API o un token de Firebase Auth para evitar el abuso del endpoint público.

Casos de uso típicos en aplicaciones móviles

Cloud Functions se utilizan más comúnmente para tareas que no pueden o no deben realizarse en el cliente: envío de notificaciones push, generación de vistas previas de imágenes subidas, integración con sistemas de pago externos, moderación de contenido, sincronización de datos entre Firebase y servicios de terceros. El modelo sin servidor hace que estas tareas sean rentables: se paga solo por el tiempo de ejecución real del código.

La integración con sistemas de pago es un escenario típico para aplicaciones con compras dentro de la aplicación. Cloud Functions recibe un webhook del proveedor de pagos (Stripe, PayPal), verifica la firma de la solicitud, actualiza el estado de la suscripción en Firestore y envía una confirmación al usuario. Todo el código se ejecuta en el servidor sin riesgo de manipulación de datos en el cliente. Según la documentación de Stripe (2026), el procesamiento del webhook toma menos de 500 ms.

La moderación inteligente de contenido utiliza un desencadenador de Storage de Cloud Function para verificar automáticamente las imágenes subidas mediante Google Cloud Vision API. La función envía la imagen a Vision API para detectar contenido no seguro (violencia, contenido para adultos) y, si se supera el umbral, elimina el archivo y notifica al administrador. Este escenario es crítico para aplicaciones UGC con galerías de usuarios.

La agregación de datos — Cloud Functions como reemplazo de los contadores de Firebase Realtime Database. En lugar de leer y escribir un contador en el cliente (lo que provoca condiciones de carrera), use un desencadenador onWrite de Firestore para actualizaciones atómicas de campos agregados. Por ejemplo, una función cuenta el número de likes de una publicación cada vez que se añade o elimina un documento en la subcolección /posts/{postId}/likes/{userId} y actualiza el campo likesCount en el documento padre.