Firebase Functions provides the Firebase SDK for Cloud Functions, enabling developers to build serverless backend logic that automatically responds to Firebase and HTTPS events. It offers comprehensive APIs for both v1 (legacy) and v2 (current generation) Cloud Functions with extensive provider integrations including Firestore, Realtime Database, Authentication, Storage, Pub/Sub, Analytics, Remote Config, Test Lab, and various alerting systems.
npm install firebase-functionsimport * as functions from "firebase-functions";
import { setGlobalOptions } from "firebase-functions/options";
import { onRequest, onCall } from "firebase-functions/https";
import { onDocumentCreated } from "firebase-functions/firestore";import * as functions from "firebase-functions/v1";
import * as https from "firebase-functions/v1/https";
import * as firestore from "firebase-functions/v1/firestore";import { info, warn, error } from "firebase-functions/logger";
import { defineString, defineBoolean } from "firebase-functions/params";For CommonJS:
const functions = require("firebase-functions");
const { onRequest } = require("firebase-functions/https");
const { info } = require("firebase-functions/logger");import { onRequest, onCall } from "firebase-functions/https";
import { onDocumentCreated } from "firebase-functions/firestore";
import { setGlobalOptions } from "firebase-functions/options";
import { info } from "firebase-functions/logger";
// Set global configuration
setGlobalOptions({
region: "us-central1",
memory: "1GiB"
});
// HTTP function
export const api = onRequest((request, response) => {
info("Processing HTTP request", { url: request.url });
response.json({ message: "Hello from Firebase!" });
});
// Callable function with data validation
export const processOrder = onCall<{orderId: string}>({
region: "us-central1",
enforceAppCheck: true
}, (request) => {
const { orderId } = request.data;
info("Processing order", { orderId });
return { success: true, orderId };
});
// Firestore trigger
export const onUserCreate = onDocumentCreated("users/{userId}", (event) => {
const userData = event.data?.data();
info("New user created", { userId: event.params.userId, userData });
});import * as functions from "firebase-functions/v1";
// HTTP function
export const legacyApi = functions.https.onRequest((req, res) => {
res.json({ message: "Legacy function" });
});
// Firestore trigger
export const legacyUserCreate = functions.firestore
.document("users/{userId}")
.onCreate((snapshot, context) => {
const userData = snapshot.data();
console.log("User created:", context.params.userId);
});Firebase Functions is built around several key architectural components:
EventContext for metadataComplete legacy API with traditional function builders and event handlers for all Firebase services.
// Function builder pattern
class FunctionBuilder {
region(...regions: Array<string | Expression<string> | ResetValue>): FunctionBuilder;
runWith(runtimeOptions: RuntimeOptions): FunctionBuilder;
}
// Core function types
interface CloudFunction<T> extends Runnable<T> {
(input: any, context?: any): PromiseLike<any> | any;
}
interface HttpsFunction {
(req: Request, resp: Response): void | Promise<void>;
}
// Event context for V1 functions
interface EventContext<Params = Record<string, string>> {
auth?: { uid: string; token: EventContextAuthToken };
authType?: "ADMIN" | "USER" | "UNAUTHENTICATED";
eventId: string;
eventType: string;
params: Params;
resource: Resource;
timestamp: string;
}Modern CloudEvents-compliant API with enhanced configuration and streaming support.
// CloudEvents specification compliance
interface CloudEvent<T> {
readonly specversion: "1.0";
id: string;
source: string;
subject?: string;
type: string;
time: string;
data: T;
}
interface CloudFunction<EventType extends CloudEvent<unknown>> {
(raw: CloudEvent<unknown>): any | Promise<any>;
run(event: EventType): any | Promise<any>;
}
// Enhanced configuration options
interface GlobalOptions {
omit?: boolean | Expression<boolean>;
region?: SupportedRegion | string | Expression<string> | ResetValue;
memory?: MemoryOption | Expression<number> | ResetValue;
concurrency?: number | Expression<number> | ResetValue;
cpu?: number | "gcf_gen1";
invoker?: "public" | "private" | string | string[];
}
// V2 memory options (up to 32GB)
type MemoryOption = "128MiB" | "256MiB" | "512MiB" | "1GiB" | "2GiB" | "4GiB" | "8GiB" | "16GiB" | "32GiB";HTTP request handlers and callable functions with CORS, authentication, and streaming support.
// V2 HTTPS with enhanced features
function onRequest(
opts: HttpsOptions,
handler: (request: Request, response: express.Response) => void | Promise<void>
): HttpsFunction;
function onCall<T, Return, Stream>(
opts: CallableOptions<T>,
handler: (request: CallableRequest<T>, response?: CallableResponse<Stream>) => Return
): CallableFunction<T, Return, Stream>;
interface CallableOptions<T = any> extends HttpsOptions {
enforceAppCheck?: boolean;
consumeAppCheckToken?: boolean;
heartbeatSeconds?: number | null;
}Realtime Database and Firestore change event handlers with path parameter extraction.
// V2 Firestore triggers
function onDocumentCreated<Document = DocumentData>(
document: string,
handler: (event: FirestoreEvent<Document | undefined, ParamsOf<string>>) => any | Promise<any>
): CloudFunction<FirestoreEvent<Document | undefined, ParamsOf<string>>>;
// V1 Firestore triggers
interface DocumentBuilder<Path extends string> {
onWrite(handler: (change: Change<DocumentSnapshot>, context: EventContext<ParamsOf<Path>>) => PromiseLike<any> | any): CloudFunction<Change<DocumentSnapshot>>;
}Firebase Authentication and Identity Platform user lifecycle events and blocking functions.
// V1 Auth blocking functions
interface UserBuilder {
beforeCreate(handler: (user: AuthUserRecord, context: AuthEventContext) => MaybeAsync<BeforeCreateResponse | void>): BlockingFunction;
beforeSignIn(handler: (user: AuthUserRecord, context: AuthEventContext) => MaybeAsync<BeforeSignInResponse | void>): BlockingFunction;
}
// V2 Identity Platform
function onUserDeleted(
handler: (event: AuthUserRecord) => any | Promise<any>
): CloudFunction<AuthUserRecord>;Pub/Sub, Task Queues, Scheduler, and custom event handling with enhanced retry and rate limiting.
// V2 Pub/Sub
function onMessagePublished(
topic: string,
handler: (event: CloudEvent<MessagePublishedData>) => any | Promise<any>
): CloudFunction<CloudEvent<MessagePublishedData>>;
// V2 Task Queues
function onTaskDispatched<Args = any>(
opts: TaskQueueOptions,
handler: (request: TaskQueueEvent<Args>) => any | Promise<any>
): CloudFunction<TaskQueueEvent<Args>>;Firebase Alerts for App Distribution, Billing, Crashlytics, and Performance Monitoring.
// Main alerts
function onAlertPublished(
alertType: string,
handler: (event: FirebaseAlertData) => any | Promise<any>
): CloudFunction<FirebaseAlertData>;
// Specialized alert handlers
function onNewFatalIssuePublished(
handler: (event: CrashlyticsNewFatalIssuePayload) => any | Promise<any>
): CloudFunction<CrashlyticsNewFatalIssuePayload>;Structured logging compatible with Cloud Logging with severity levels and metadata support.
type LogSeverity = "DEBUG" | "INFO" | "NOTICE" | "WARNING" | "ERROR" | "CRITICAL" | "ALERT" | "EMERGENCY";
interface LogEntry {
severity: LogSeverity;
message?: string;
[key: string]: any;
}
function write(entry: LogEntry): void;
function info(...args: any[]): void;
function error(...args: any[]): void;Environment parameter management with CLI integration supporting multiple data types and validation.
abstract class Param<T extends string | number | boolean | string[]> extends Expression<T> {
constructor(name: string, options?: ParamOptions<T>);
equals(rhs: T | Expression<T>): CompareExpression<T>;
}
function defineString(name: string, options?: ParamOptions<string>): StringParam;
function defineBoolean(name: string, options?: ParamOptions<boolean>): BooleanParam;
function defineSecret(name: string): SecretParam;
// Built-in parameters
const projectID: Param<string>;
const databaseURL: Param<string>;
const storageBucket: Param<string>;Cloud Storage object change events with metadata and content processing capabilities.
// V2 Storage
function onObjectFinalized(
handler: (event: CloudEvent<StorageObjectData>) => any | Promise<any>
): CloudFunction<CloudEvent<StorageObjectData>>;
// V1 Storage
interface ObjectBuilder {
onFinalize(handler: (object: ObjectMetadata, context: EventContext) => PromiseLike<any> | any): CloudFunction<ObjectMetadata>;
onMetadataUpdate(handler: (object: ObjectMetadata, context: EventContext) => PromiseLike<any> | any): CloudFunction<ObjectMetadata>;
}Google Analytics event processing and Firebase Test Lab integration for comprehensive app analytics.
// V1 Analytics
function event(analyticsEventType: string): AnalyticsEventBuilder;
interface AnalyticsEventBuilder {
onLog(handler: (event: AnalyticsEvent, context: EventContext) => PromiseLike<any> | any): CloudFunction<AnalyticsEvent>;
}
// Test Lab
interface TestMatrixBuilder {
onComplete(handler: (testMatrix: TestMatrix, context: EventContext) => PromiseLike<any> | any): CloudFunction<TestMatrix>;
}// Extract path parameters from template strings
type ParamsOf<Path extends string> = Path extends `${infer _Prefix}/{${infer Param}}${infer Suffix}`
? { [K in Param | keyof ParamsOf<Suffix>]: string }
: {};
// Change detection for before/after comparisons
interface Change<T> {
before: T;
after: T;
}// V1 memory options
const VALID_MEMORY_OPTIONS = ["128MB", "256MB", "512MB", "1GB", "2GB", "4GB", "8GB"] as const;
// V2 memory options (enhanced)
type MemoryOption = "128MiB" | "256MiB" | "512MiB" | "1GiB" | "2GiB" | "4GiB" | "8GiB" | "16GiB" | "32GiB";
// Supported regions
type SupportedRegion = "us-central1" | "us-east1" | "us-east4" | "us-west1" | "us-west2" | "us-west3" | "us-west4" |
"europe-west1" | "europe-west2" | "europe-west3" | "europe-west6" | "europe-central2" |
"asia-east1" | "asia-east2" | "asia-northeast1" | "asia-northeast2" | "asia-northeast3" |
"asia-south1" | "asia-southeast1" | "asia-southeast2" | "australia-southeast1" |
"northamerica-northeast1" | "southamerica-east1";// Parameter expressions for dynamic configuration
abstract class Expression<T extends string | number | boolean | string[]> {
value(): T;
toCEL(): string;
toJSON(): string;
}
// Reset values for configuration overrides
interface ResetValue {
__reset: true;
}