Firebase Cloud Functions — co to je, triggery a jak psát funkce

Co je Firebase Cloud Functions a jak je uspořádán

Firebase Cloud Functions je výpočetní platforma postavená na základě Google Cloud Functions (GCF), přizpůsobená ekosystému Firebase. Funkce představují běžný kód JavaScript nebo TypeScript, exportovaný z modulu a registrovaný pro určitý typ události. Když událost nastane (například se uživatel registruje nebo nahrává soubor), Firebase Cloud Functions spustí odpovídající kód a předá mu kontext události.

Architektura Cloud Functions se řídí zásadou jedné odpovědnosti: jedna funkce zpracovává jeden typ události a provádí jednu atomickou operaci. Například funkce sendWelcomeEmail se volá při vytvoření nového uživatele ve Firebase Authentication a odesílá uvítací dopis. Taková izolace zjednodušuje ladění, testování a opětovné použití funkcí v různých projektech.

Každá funkce běží v izolovaném kontejneru s dočasným životním cyklem. Maximální doba běhu je ve výchozím nastavení 60 sekund (funkce HTTPS — 9 minut). Pokud se funkce nevejde do časového limitu, požadavek skončí chybou 500. Pro dlouhé operace používejte Cloud Tasks nebo Pub/Sub s opakovanými pokusy. Kontejnery lze znovu použít pro následující volání (keep-alive), což snižuje zpoždění při studených startech po prvním volání.

Běhové prostředí a verze Node.js

Firebase Cloud Functions podporuje několik verzí Node.js: 18, 20 a 22 (doporučená pro nové projekty). Výběr verze se nastavuje v poli engines souboru package.json. Firebase CLI automaticky konfiguruje běhové prostředí na základě zadané verze. Důležité: Firebase Cloud Functions nepodporuje spouštění libovolných kontejnerů Docker — prostředí je přísně stanoveno službou Google Cloud Functions.

Pro nové projekty se doporučuje Node.js 22, protože obsahuje nejnovější optimalizace V8, vylepšenou práci s moduly ESM a podporu WebSocket na úrovni platformy. Pokud projekt používá závislosti sestavené pro konkrétní verzi Node (například nativní moduly C++), je třeba kompatibilitu ověřit zvlášť — ne všechny nativní moduly se v prostředí GCF zkompilují.

Rozdíl mezi Firebase Cloud Functions a Google Cloud Functions

Firebase Cloud Functions je obálka nad Google Cloud Functions s předinstalovaným Firebase SDK a integrací se službami Firebase. Vývojář píše kód pomocí SDK firebase-functions, které poskytuje typované triggery pro všechny služby Firebase. Google Cloud Functions je platforma nižší úrovně, kde se triggery konfigurují explicitně přes Eventarc nebo Pub/Sub.

Klíčový rozdíl: ve Firebase Cloud Functions se trigger registruje deklarativně voláním functions.firestore.document('path').onWrite(), v Google Cloud Functions pak — konfigurací Eventarc s filtrováním podle atributů události. Firebase Cloud Functions je také automaticky dodáván s Admin SDK, inicializovaným s oprávněními servisního účtu projektu, což poskytuje plný přístup ke všem službám Firebase bez další konfigurace.

Typy triggerů: které události jsou podporovány

Firebase Cloud Functions podporuje 8 kategorií triggerů, z nichž každá odpovídá určité službě Firebase nebo Google Cloud. Trigger je podmínka, při jejímž nastání je funkce volána automaticky. Vývojář neřídí životní cyklus funkce přímo: Firebase CLI registruje trigger v Google Cloud Eventarc a cloudová platforma sama spouští funkci při nastání události.

Nejoblíbenější triggery — triggery Firestore: onWrite, onCreate, onUpdate, onDelete. Aktivují se při změně dokumentů v kolekcích Firestore. Funkce získá snímky dokumentu před a po změně, což umožňuje porovnávat hodnoty a reagovat pouze na určité změny. Například při změně stavu objednávky z "pending" na "shipped" můžete uživateli odeslat push notifikaci.

Triggery Authentication (onCreate, onDelete) se aktivují při vytvoření nebo odstranění účtu. Slouží k inicializaci uživatelských dat: vytvoření dokumentu uživatele ve Firestore, odeslání uvítacího e-mailu, zápisu do analytiky. Důležité: funkce nemůže zrušit vytvoření uživatele — běží poté, co byl účet již vytvořen. Pro předběžnou validaci používejte blokující funkce (Blocking Functions), dostupné na platformě Identity Platform.

Triggery HTTPS a CORS

Funkce HTTPS (onRequest) umožňují vytvářet plnohodnotné endpointy REST API, dostupné přes HTTP. Na rozdíl od triggerů událostí se funkce HTTPS volají přes URL ve tvaru https://{region}-{project}.cloudfunctions.net/{functionName}. Důležité je správně nakonfigurovat CORS, pokud je endpoint volán z prohlížeče nebo mobilní aplikace. Firebase SDK nezahrnuje automaticky hlavičky CORS — je třeba je přidat ručně přes middleware.

Pro mobilní klienty (Android, iOS) není CORS nutný, protože nativní HTTP klienti nejsou omezeni politikou Cross-Origin. CORS je relevantní pouze pro webové požadavky. Pokud je vaše funkce HTTPS volána z aplikace i z webu, přidejte univerzální zpracování CORS: res.set('Access-Control-Allow-Origin', '*') pro development nebo seznam povolených domén pro production.

Plánování pomocí Pub/Sub a Cloud Scheduler

Pro periodické spouštění (úlohy cron) používejte kombinaci Cloud Scheduler a Pub/Sub. Cloud Scheduler odesílá zprávu do tématu Pub/Sub podle plánu a trigger onPublish tuto zprávu zpracovává. Firebase CLI nepodporuje přímou syntaxi cron — plán se nastavuje v konzoli Google Cloud nebo Terraformu ve formátu unix-cron: 0 3 * * * (denně ve 3:00).

Příklady úloh: denní rozesílka, čištění zastaralých dat, generování sestav, synchronizace s externími API. Důležité: Cloud Scheduler je placená služba Google Cloud (přibližně 2 $ měsíčně za jednu úlohu). Každé aktivování se počítá jako samostatné volání funkce a účtuje se podle standardních cen Cloud Functions.

Jak psát a nasazovat funkce

Vývoj Cloud Functions začíná inicializací projektu přes Firebase CLI: firebase init functions. Tento příkaz vytvoří adresář functions/ se šablonou index.js (nebo index.ts), souborem package.json a konfigurací TypeScript (pokud je vybrán). Po inicializaci stačí napsat funkci, exportovat ji z modulu a spustit firebase deploy --only functions pro nasazení.

Každá funkce se registruje voláním metody odpovídajícího triggeru. Příklad funkce HTTPS: exports.helloWorld = functions.https.onRequest((req, res) => { res.send("Hello!"); }). Funkce Firebase používají asynchronní model: pro triggery událostí (ne HTTPS) musí funkce vracet Promise. Firebase čeká na dokončení Promise před uzavřením kontejneru. Pokud se Promise nevrátí, funkce může být přerušena před dokončením asynchronních operací.

Lokální vývoj probíhá přes Firebase Emulator Suite, které zahrnuje emulátor Cloud Functions. Příkaz firebase emulators:start spustí lokální server s funkcemi, dostupný na adrese http://localhost:5001. Emulátor podporuje hot reload při změně kódu a je zcela izolován od produkčního prostředí, což umožňuje testovat funkce bez rizika ovlivnění reálných dat.

Správa závislostí a konfigurace

Závislosti Cloud Functions se spravují přes package.json. Firebase instaluje pouze produkční závislosti (dependencies, ne devDependencies). Velikost balíčku funkcí ovlivňuje dobu studeného startu: doporučuje se minimalizovat počet závislostí. Pro práci s Firebase Admin SDK je závislost firebase-admin již předinstalovaná — není třeba ji přidávat ručně.

Důvěrné údaje (klíče API, tokeny) by neměly být uloženy v kódu funkce. K uložení konfigurace používejte functions.config(): firebase functions:config:set stripe.key="sk_...". Hodnoty jsou šifrované a v runtime dostupné přes functions.config().stripe.key. Pro velké serializované konfigurace používejte Secret Manager Google Cloud.

Zpracování chyb a logování

Logování v Cloud Functions probíhá přes console.log, console.warn a console.error. Všechny logy se automaticky shromažďují v Google Cloud Logging a jsou dostupné v konzoli Firebase (sekce Functions > Logs). Pro strukturované logování používejte knihovnu winston nebo pino, které podporují formátování JSON a úrovně logování.

Zpracování chyb je kritické pro spolehlivost: neošetřená výjimka v Promise ukončí funkci chybou, poté Firebase automaticky opakuje volání (retry) s exponenciálním zpožděním. Počet opakování se konfiguruje: od 0 do nekonečna. Pro triggery událostí se doporučuje zapnout retry, aby bylo zaručeno zpracování každé události i při dočasných výpadcích externích služeb.

Studený start a škálování

Studený start (cold start) je zpoždění při prvním volání funkce po období nečinnosti, kdy se kontejner s kódem znovu načítá a inicializuje. Podle Firebase documentation (2026) trvá studený start od 200 ms do 2 sekund v závislosti na velikosti balíčku, počtu závislostí a regionu. Pro uživatelské rozhraní je zpoždění nad 1 sekundu znatelné a může ovlivnit user experience.

Způsoby minimalizace studeného startu: minimalizace závislostí, použití TypeScript s kompilací do CommonJS, zmenšení balíčku funkcí, nastavení minimálního počtu aktivních instancí. Firebase Cloud Functions v2 (2nd gen) umožňuje nastavit minInstances — minimální počet zahřátých kontejnerů, které jsou vždy připraveny ke zpracování požadavků. Za zahřívání kontejnerů se účtuje poplatek za dobu nečinnosti.

Škálování Cloud Functions probíhá automaticky: při nárůstu počtu požadavků Firebase vytváří nové kontejnery. Ve výchozím nastavení je maximální počet paralelních instancí 3000 (kvóta projektu Google Cloud). Každá instance zpracovává jeden požadavek najednou. Pokud je funkce rychlá (méně než 100 ms), může jedna instance zpracovat až 10 požadavků za sekundu, což dává špičkovou propustnost až 30 000 požadavků za sekundu na projekt.

Nastavení minInstances a maxInstances

minInstances je parametr, který rezervuje zadaný počet kontejnerů a udržuje je zahřáté. Doporučuje se pro kritické funkce HTTPS, kde je zpoždění studeného startu nepřijatelné. Například pro endpoint autentizace nastavte minInstances: 1. maxInstances je omezení maximálního počtu paralelních instancí, užitečné pro zabránění nekontrolovaného růstu nákladů při náhlém nárůstu provozu.

Nastavení se provádí v kódu: functions.runWith({ minInstances: 1, maxInstances: 10 }). Důležité: minInstances zvyšuje náklady, protože kontejner pracuje nepřetržitě. U testovacích projektů je třeba minInstances vypnout. Pro produkci se doporučuje minInstances pro všechny veřejné funkce HTTPS a 0 pro triggery událostí, kde zpoždění 1 sekundy není kritické.

Regiony nasazení

Region nasazení ovlivňuje zpoždění ke koncovým uživatelům a náklady na odchozí provoz. Firebase Cloud Functions je dostupný ve více než 30 regionech Google Cloud. Pro mobilní aplikace vybírejte region nejbližší vaší cílové skupině: us-central1 pro Ameriku, europe-west1 pro Evropu, asia-east2 pro Asii. Region nelze po nasazení změnit bez opětovného nasazení funkce.

Změna regionu se provádí pomocí parametru region v kódu: functions.region('europe-west1'). Všechny funkce v jednom souboru mohou mít různé regiony. Pro globální projekty se doporučuje nasadit funkce do několika regionů a použít Cloud Load Balancing pro rozložení provozu, i když pro většinu mobilních aplikací stačí jeden region při správné volbě.

Příklady kódu pro Firebase Cloud Functions

Podívejme se na praktické příklady Cloud Functions v TypeScript. Kód používá Firebase Functions SDK v2 (2nd gen) s modulární syntaxí ES. Příklady zahrnují zpracování události vytvoření uživatele, generování miniatury při nahrání obrázku a jednoduchý endpoint HTTPS pro REST API. Všechny funkce jsou asynchronní s vrácením Promise pro správné ukončení kontejneru.

Před spuštěním se ujistěte, že je Firebase CLI aktualizováno na verzi 13+: npm install -g firebase-tools. Funkce v2 vyžadují tarifní plán Blaze. Inicializace: firebase init functions s výběrem TypeScript.

Zpracování registrace uživatele

První příklad — vytvoření dokumentu ve Firestore při registraci nového uživatele. Funkce je spuštěna událostí auth.user().onCreate a zapisuje základní profil do kolekce users/{uid}. To umožňuje zaručit, že pro každého registrovaného uživatele existuje dokument s potřebnými poli.

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}`)
    })

Funkce createUserProfile je asynchronní — vrací Promise, který Firebase očekává před dokončením. Pokud zápis do Firestore skončí chybou (například kvůli nedostatku oprávnění), funkce se automaticky zopakuje (pokud je retry zapnuto). Pole role s hodnotou "free" umožňuje implementovat omezení bezplatného tarifu přímo v Security Rules Firestore, porovnáním resource.data.role s požadovanou úrovní přístupu.

Generování miniatury při nahrání obrázku

Druhý příklad — trigger Storage pro automatické generování miniatury (thumbnail) po nahrání obrázku. Funkce vytvoří zmenšenou kopii o velikosti 200x200 pixelů a uloží ji do cesty zdrojového souboru s předponou thumb_. Pro zpracování obrázků se používá knihovna sharp, která podporuje všechny běžné formáty a funguje v prostředí Node.js bez systémových závislostí.

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 })
    })

Funkce generateThumbnail kontroluje Content-Type objektu a ignoruje ne-obrázky, což šetří prostředky. Pro práci se sharp musí být závislost přidána do package.json. Miniatura se vytváří s parametrem fit: "cover", který ořeže obrázek ve středu na čtverec 200x200 pixelů. Po vytvoření se miniatura nahraje zpět do stejného bucketu s upraveným názvem.

Endpoint HTTPS pro veřejné API

Třetí příklad — funkce HTTPS, která implementuje endpoint REST API pro kontrolu stavu serveru. Funkce přijímá požadavek GET a vrací JSON s informacemi o stavu služeb Firebase připojených k projektu. Endpoint je užitečný pro monitorování a pro externí systémy, které potřebují zkontrolovat dostupnost backendu před odesláním dat.

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)

Funkce api používá express Router pro směrování, což je vhodné při vytváření více endpointů v jedné funkci. Health check se zapisuje do Firestore do kolekce _health, což umožňuje zároveň ověřit dostupnost Firestore. Pro produkci se doporučuje přidat autentizaci požadavku pomocí klíče API nebo tokenu Firebase Auth, aby se zabránilo zneužití veřejného endpointu.

Typické scénáře použití v mobilních aplikacích

Cloud Functions se nejčastěji používají pro úlohy, které nelze nebo není vhodné vykonávat na klientovi: odesílání push notifikací, generování náhledů nahraných obrázků, integrace s externími platebními systémy, moderace obsahu, synchronizace dat mezi Firebase a službami třetích stran. Model bez serveru dělá tyto úlohy ekonomickými: poplatek se účtuje pouze za skutečnou dobu běhu kódu.

Integrace s platebními systémy je typický scénář pro aplikace s nákupy in-app. Cloud Functions obdrží webhook od poskytovatele plateb (Stripe, PayPal), ověří podpis požadavku, aktualizuje stav předplatného ve Firestore a odešle uživateli potvrzení. Celý kód běží na serveru bez rizika záměny dat na klientovi. Podle Stripe documentation (2026) trvá zpracování webhooku méně než 500 ms.

Chytrá moderace obsahu používá trigger Storage pro automatickou kontrolu nahraných obrázků přes Google Cloud Vision API. Funkce odešle obrázek do Vision API pro detekci nebezpečného obsahu (násilí, obsah pro dospělé) a pokud je práh překročen, smaže soubor a upozorní administrátora. Tento scénář je kritický pro aplikace UGC s uživatelskými galeriemi.

Agregace dat — Cloud Functions jako náhrada počítadel Firebase Realtime Database. Místo čtení a zápisu počítadla na klientovi (což vede k race conditions) použijte trigger Firestore onWrite pro atomickou aktualizaci agregovaných polí. Například funkce počítá počet lajků příspěvku při každém přidání nebo odstranění dokumentu v podkolekci /posts/{postId}/likes/{userId} a aktualizuje pole likesCount v nadřazeném dokumentu.