Firebase Cloud Functions — apa itu, pemicu dan cara menulis fungsi

Apa itu Firebase Cloud Functions dan bagaimana strukturnya

Firebase Cloud Functions adalah platform komputasi yang dibangun di atas Google Cloud Functions (GCF), yang disesuaikan untuk ekosistem Firebase. Fungsi adalah kode JavaScript atau TypeScript biasa yang diekspor dari modul dan didaftarkan untuk jenis peristiwa tertentu. Ketika peristiwa terjadi (misalnya, pengguna mendaftar atau mengunggah file), Firebase Cloud Functions menjalankan kode yang sesuai, meneruskan konteks peristiwa ke kode tersebut.

Arsitektur Cloud Functions mengikuti prinsip tanggung jawab tunggal: satu fungsi memproses satu jenis peristiwa dan melakukan satu operasi atomik. Misalnya, fungsi sendWelcomeEmail dipanggil saat pengguna baru dibuat di Firebase Authentication dan mengirim email selamat datang. Isolasi semacam ini menyederhanakan debugging, pengujian, dan penggunaan kembali fungsi di berbagai proyek.

Setiap fungsi berjalan di kontainer terisolasi dengan siklus hidup sementara. Waktu eksekusi maksimum secara default adalah 60 detik (fungsi HTTPS — 9 menit). Jika fungsi tidak sesuai dengan batas waktu, permintaan berakhir dengan error 500. Untuk operasi yang lama gunakan Cloud Tasks atau Pub/Sub dengan percobaan ulang. Kontainer dapat digunakan kembali untuk panggilan berikutnya (keep-alive), yang mengurangi latensi pada cold start setelah panggilan pertama.

Lingkungan eksekusi dan versi Node.js

Firebase Cloud Functions mendukung beberapa versi Node.js: 18, 20, dan 22 (direkomendasikan untuk proyek baru). Pemilihan versi diatur di bidang engines pada file package.json. Firebase CLI otomatis mengonfigurasi lingkungan eksekusi berdasarkan versi yang ditentukan. Penting: Firebase Cloud Functions tidak mendukung menjalankan kontainer Docker arbitrer — lingkungannya ditentukan secara ketat oleh Google Cloud Functions.

Untuk proyek baru disarankan Node.js 22, karena mencakup optimasi V8 terbaru, kerja yang lebih baik dengan modul ESM, dan dukungan WebSocket di tingkat platform. Jika proyek menggunakan dependensi yang dikompilasi untuk versi Node tertentu (misalnya, modul native C++), kompatibilitas perlu diperiksa secara terpisah — tidak semua modul native terkompilasi di lingkungan GCF.

Perbedaan antara Firebase Cloud Functions dan Google Cloud Functions

Firebase Cloud Functions adalah pembungkus di atas Google Cloud Functions dengan Firebase SDK yang terpasang sebelumnya dan integrasi dengan layanan Firebase. Pengembang menulis kode menggunakan SDK firebase-functions, yang menyediakan pemicu bertipe untuk semua layanan Firebase. Google Cloud Functions adalah platform level lebih rendah, di mana pemicu dikonfigurasi secara eksplisit melalui Eventarc atau Pub/Sub.

Perbedaan utama: di Firebase Cloud Functions pemicu didaftarkan secara deklaratif melalui panggilan functions.firestore.document('path').onWrite(), sedangkan di Google Cloud Functions — melalui konfigurasi Eventarc dengan penyaringan berdasarkan atribut peristiwa. Firebase Cloud Functions juga otomatis hadir dengan Admin SDK, yang diinisialisasi dengan hak akun layanan proyek, memberikan akses penuh ke semua layanan Firebase tanpa konfigurasi tambahan.

Jenis pemicu: peristiwa apa saja yang didukung

Firebase Cloud Functions mendukung 8 kategori pemicu, masing-masing sesuai dengan layanan Firebase atau Google Cloud tertentu. Pemicu adalah kondisi yang saat terjadi fungsi dipanggil secara otomatis. Pengembang tidak mengelola siklus hidup fungsi secara langsung: Firebase CLI mendaftarkan pemicu di Google Cloud Eventarc, dan platform cloud sendiri menjalankan fungsi saat peristiwa terjadi.

Pemicu paling populer — pemicu Firestore: onWrite, onCreate, onUpdate, onDelete. Pemicu ini terpicu saat dokumen di koleksi Firestore berubah. Fungsi menerima snapshot dokumen sebelum dan sesudah perubahan, yang memungkinkan membandingkan nilai dan bereaksi hanya pada perubahan tertentu. Misalnya, saat status pesanan berubah dari "pending" menjadi "shipped", Anda dapat mengirim notifikasi push kepada pengguna.

Pemicu Authentication (onCreate, onDelete) terpicu saat akun dibuat atau dihapus. Digunakan untuk menginisialisasi data pengguna: membuat dokumen pengguna di Firestore, mengirim email selamat datang, menulis ke analitik. Penting: fungsi tidak dapat membatalkan pembuatan pengguna — fungsi berjalan setelah akun sudah dibuat. Untuk validasi awal gunakan fungsi pemblokiran (Blocking Functions), yang tersedia di platform Identity Platform.

Pemicu HTTPS dan CORS

Fungsi HTTPS (onRequest) memungkinkan membuat endpoint REST API lengkap yang dapat diakses melalui HTTP. Berbeda dengan pemicu peristiwa, fungsi HTTPS dipanggil melalui URL berbentuk https://{region}-{project}.cloudfunctions.net/{functionName}. Penting untuk mengonfigurasi CORS dengan benar jika endpoint dipanggil dari browser atau aplikasi seluler. Firebase SDK tidak menyertakan header CORS secara otomatis — header tersebut perlu ditambahkan secara manual melalui middleware.

Untuk klien seluler (Android, iOS) CORS tidak diperlukan, karena klien HTTP native tidak dibatasi oleh kebijakan Cross-Origin. CORS hanya relevan untuk permintaan web. Jika fungsi HTTPS Anda dipanggil baik dari aplikasi maupun dari web, tambahkan penanganan CORS universal: res.set('Access-Control-Allow-Origin', '*') untuk development atau daftar domain yang diizinkan untuk production.

Penjadwalan dengan Pub/Sub dan Cloud Scheduler

Untuk eksekusi berkala (tugas cron) gunakan kombinasi Cloud Scheduler dan Pub/Sub. Cloud Scheduler mengirim pesan ke topik Pub/Sub sesuai jadwal, dan pemicu onPublish memproses pesan tersebut. Firebase CLI tidak mendukung sintaks cron langsung — jadwal diatur melalui konsol Google Cloud atau Terraform dalam format unix-cron: 0 3 * * * (setiap hari pukul 3:00).

Contoh tugas: pengiriman harian, pembersihan data usang, pembuatan laporan, sinkronisasi dengan API eksternal. Penting: Cloud Scheduler adalah layanan berbayar Google Cloud (sekitar $2 per bulan untuk satu job). Setiap pemicuan dihitung sebagai panggilan fungsi terpisah dan ditagih dengan harga standar Cloud Functions.

Cara menulis dan men-deploy fungsi

Pengembangan Cloud Functions dimulai dengan inisialisasi proyek melalui Firebase CLI: firebase init functions. Perintah ini membuat direktori functions/ dengan template index.js (atau index.ts), file package.json, dan konfigurasi TypeScript (jika dipilih). Setelah inisialisasi, cukup menulis fungsi, mengekspornya dari modul, dan menjalankan firebase deploy --only functions untuk deploy.

Setiap fungsi didaftarkan melalui panggilan metode pemicu yang sesuai. Contoh fungsi HTTPS: exports.helloWorld = functions.https.onRequest((req, res) => { res.send("Hello!"); }). Fungsi Firebase menggunakan model asinkron: untuk pemicu peristiwa (bukan HTTPS) fungsi harus mengembalikan Promise. Firebase menunggu Promise selesai sebelum menutup kontainer. Jika Promise tidak dikembalikan, fungsi dapat dihentikan sebelum operasi asinkron selesai.

Pengembangan lokal dilakukan melalui Firebase Emulator Suite, yang mencakup emulator Cloud Functions. Perintah firebase emulators:start menjalankan server lokal dengan fungsi, yang dapat diakses di http://localhost:5001. Emulator mendukung hot reload saat kode berubah dan sepenuhnya terisolasi dari lingkungan produksi, sehingga fungsi dapat diuji tanpa risiko memengaruhi data nyata.

Pengelolaan dependensi dan konfigurasi

Dependensi Cloud Functions dikelola melalui package.json. Firebase hanya memasang dependensi produksi (dependencies, bukan devDependencies). Ukuran paket fungsi memengaruhi waktu cold start: disarankan meminimalkan jumlah dependensi. Untuk bekerja dengan Firebase Admin SDK, dependensi firebase-admin sudah terpasang sebelumnya — tidak perlu menambahkannya secara manual.

Data rahasia (kunci API, token) tidak boleh disimpan di kode fungsi. Gunakan functions.config() untuk menyimpan konfigurasi: firebase functions:config:set stripe.key="sk_...". Nilai dienkripsi dan tersedia di runtime melalui functions.config().stripe.key. Untuk konfigurasi serial yang besar gunakan Google Cloud Secret Manager.

Penanganan error dan pencatatan log

Pencatatan log di Cloud Functions dilakukan melalui console.log, console.warn, dan console.error. Semua log otomatis dikumpulkan di Google Cloud Logging dan tersedia di konsol Firebase (bagian Functions > Logs). Untuk pencatatan log terstruktur gunakan pustaka winston atau pino, yang mendukung format JSON dan tingkat log.

Penanganan error sangat penting untuk keandalan: pengecualian yang tidak tertangani di Promise mengakhiri fungsi dengan error, setelah itu Firebase otomatis mengulangi panggilan (retry) dengan penundaan eksponensial. Jumlah retry dapat dikonfigurasi: dari 0 hingga tak terbatas. Untuk pemicu peristiwa disarankan mengaktifkan retry untuk menjamin pemrosesan setiap peristiwa bahkan saat layanan eksternal mengalami gangguan sementara.

Cold start dan penskalaan

Cold start adalah penundaan pada panggilan pertama fungsi setelah periode tidak aktif, ketika kontainer dengan kode dimuat dan diinisialisasi ulang. Menurut Firebase documentation (2026), cold start berlangsung dari 200 ms hingga 2 detik tergantung ukuran paket, jumlah dependensi, dan wilayah. Untuk antarmuka pengguna, penundaan lebih dari 1 detik terasa dan dapat memengaruhi user experience.

Cara meminimalkan cold start: meminimalkan dependensi, menggunakan TypeScript dengan kompilasi ke CommonJS, mengurangi ukuran paket fungsi, mengatur jumlah minimum instans aktif. Firebase Cloud Functions v2 (2nd gen) memungkinkan mengatur minInstances — jumlah minimum kontainer yang dipanaskan, yang selalu siap memproses permintaan. Untuk pemanasan kontainer dikenakan biaya untuk waktu idle.

Penskalaan Cloud Functions terjadi otomatis: saat jumlah permintaan meningkat, Firebase membuat kontainer baru. Secara default jumlah maksimum instans paralel adalah 3000 (kuota proyek Google Cloud). Setiap instans memproses satu permintaan pada satu waktu. Jika fungsi cepat (kurang dari 100 ms), satu instans dapat memproses hingga 10 permintaan per detik, memberikan throughput puncak hingga 30 000 permintaan per detik per proyek.

Konfigurasi minInstances dan maxInstances

minInstances adalah parameter yang mereservasi jumlah kontainer yang ditentukan dan menjaganya tetap panas. Direkomendasikan untuk fungsi HTTPS kritis, di mana penundaan cold start tidak dapat diterima. Misalnya, untuk endpoint autentikasi atur minInstances: 1. maxInstances adalah batas jumlah maksimum instans paralel, berguna untuk mencegah pertumbuhan biaya yang tidak terkendali saat lonjakan lalu lintas mendadak.

Konfigurasi dilakukan dalam kode: functions.runWith({ minInstances: 1, maxInstances: 10 }). Penting: minInstances meningkatkan biaya, karena kontainer bekerja terus-menerus. Untuk proyek pengujian minInstances harus dimatikan. Untuk produksi disarankan minInstances untuk semua fungsi HTTPS publik dan 0 untuk pemicu peristiwa, di mana penundaan 1 detik tidak kritis.

Wilayah deploy

Wilayah deploy memengaruhi penundaan ke pengguna akhir dan biaya lalu lintas keluar. Firebase Cloud Functions tersedia di 30+ wilayah Google Cloud. Untuk aplikasi seluler pilih wilayah yang paling dekat dengan audiens target Anda: us-central1 untuk Amerika, europe-west1 untuk Eropa, asia-east2 untuk Asia. Wilayah tidak dapat diubah setelah deploy tanpa men-deploy ulang fungsi.

Perubahan wilayah dilakukan melalui parameter region dalam kode: functions.region('europe-west1'). Semua fungsi dalam satu file dapat memiliki wilayah yang berbeda. Untuk proyek global disarankan men-deploy fungsi di beberapa wilayah dan menggunakan Cloud Load Balancing untuk distribusi lalu lintas, meskipun untuk sebagian besar aplikasi seluler satu wilayah cukup jika dipilih dengan benar.

Contoh kode untuk Firebase Cloud Functions

Mari kita lihat contoh praktis Cloud Functions dalam TypeScript. Kode menggunakan Firebase Functions SDK v2 (2nd gen) dengan sintaks modul ES. Contoh mencakup pemrosesan peristiwa pembuatan pengguna, pembuatan thumbnail saat unggah gambar, dan endpoint HTTPS sederhana untuk REST API. Semua fungsi bersifat asinkron dengan pengembalian Promise untuk penyelesaian kontainer yang benar.

Sebelum menjalankan, pastikan Firebase CLI diperbarui ke versi 13+: npm install -g firebase-tools. Fungsi v2 memerlukan paket tarif Blaze. Inisialisasi: firebase init functions dengan memilih TypeScript.

Pemrosesan pendaftaran pengguna

Contoh pertama — pembuatan dokumen di Firestore saat pengguna baru mendaftar. Fungsi dipicu oleh peristiwa auth.user().onCreate dan menulis profil dasar ke koleksi users/{uid}. Ini memungkinkan menjamin bahwa untuk setiap pengguna terdaftar ada dokumen dengan bidang yang diperlukan.

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

Fungsi createUserProfile bersifat asinkron — mengembalikan Promise yang ditunggu Firebase sebelum selesai. Jika penulisan ke Firestore berakhir dengan error (misalnya, karena kurangnya izin), fungsi akan diulang otomatis (jika retry diaktifkan). Bidang role dengan nilai "free" memungkinkan menerapkan batasan paket gratis langsung di Security Rules Firestore, membandingkan resource.data.role dengan tingkat akses yang diperlukan.

Pembuatan thumbnail saat unggah gambar

Contoh kedua — pemicu Storage untuk membuat miniatur (thumbnail) otomatis setelah unggah gambar. Fungsi membuat salinan yang diperkecil berukuran 200x200 piksel dan menyimpannya di jalur file sumber dengan prefiks thumb_. Untuk memproses gambar digunakan pustaka sharp, yang mendukung semua format umum dan bekerja di lingkungan Node.js tanpa dependensi sistem.

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

Fungsi generateThumbnail memeriksa Content-Type objek dan mengabaikan non-gambar, yang menghemat sumber daya. Untuk bekerja dengan sharp, dependensi harus ditambahkan ke package.json. Thumbnail dibuat dengan parameter fit: "cover", yang memotong gambar di tengah menjadi persegi 200x200 piksel. Setelah dibuat, thumbnail diunggah kembali ke bucket yang sama dengan nama yang dimodifikasi.

Endpoint HTTPS untuk API publik

Contoh ketiga — fungsi HTTPS yang mengimplementasikan endpoint REST API untuk memeriksa status server. Fungsi menerima permintaan GET dan mengembalikan JSON dengan informasi tentang status layanan Firebase yang terhubung ke proyek. Endpoint berguna untuk pemantauan dan untuk sistem eksternal yang perlu memeriksa ketersediaan backend sebelum mengirim data.

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)

Fungsi api menggunakan express Router untuk perutean, yang nyaman saat membuat beberapa endpoint dalam satu fungsi. Health check ditulis ke Firestore di koleksi _health, yang memungkinkan memeriksa ketersediaan Firestore secara bersamaan. Untuk produksi disarankan menambahkan autentikasi permintaan melalui kunci API atau token Firebase Auth untuk mencegah penyalahgunaan endpoint publik.

Skenario penggunaan umum di aplikasi seluler

Cloud Functions paling sering digunakan untuk tugas yang tidak mungkin atau tidak diinginkan dilakukan di klien: pengiriman notifikasi push, pembuatan pratinjau gambar yang diunggah, integrasi dengan sistem pembayaran eksternal, moderasi konten, sinkronisasi data antara Firebase dan layanan pihak ketiga. Model tanpa server membuat tugas-tugas ini ekonomis: biaya hanya dikenakan untuk waktu eksekusi kode yang sebenarnya.

Integrasi dengan sistem pembayaran adalah skenario umum untuk aplikasi dengan pembelian in-app. Cloud Functions menerima webhook dari penyedia pembayaran (Stripe, PayPal), memverifikasi tanda tangan permintaan, memperbarui status langganan di Firestore, dan mengirim konfirmasi kepada pengguna. Seluruh kode dijalankan di server tanpa risiko manipulasi data di klien. Menurut Stripe documentation (2026), pemrosesan webhook memakan waktu kurang dari 500 ms.

Moderasi konten cerdas menggunakan pemicu Storage untuk memeriksa gambar yang diunggah secara otomatis melalui Google Cloud Vision API. Fungsi mengirim gambar ke Vision API untuk deteksi konten tidak aman (kekerasan, konten dewasa) dan, jika ambang batas terlampaui, menghapus file dan memberi tahu administrator. Skenario ini sangat penting untuk aplikasi UGC dengan galeri pengguna.

Agregasi data — Cloud Functions sebagai pengganti penghitung Firebase Realtime Database. Alih-alih membaca dan menulis penghitung di klien (yang menyebabkan race conditions), gunakan pemicu Firestore onWrite untuk pembaruan atomik bidang agregat. Misalnya, fungsi menghitung jumlah suka postingan setiap kali dokumen ditambahkan atau dihapus di subkoleksi /posts/{postId}/likes/{userId} dan memperbarui bidang likesCount di dokumen induk.