feature: functions can now declare lifecycle hooks by wandamora · Pull Request #1915 · firebase/firebase-functions

wandamora · 2026-06-25T20:01:43Z

Description

This PR adds support for declaring codebase lifecycle hooks in the Firebase Functions SDK. Developers can now register actions (afterInstall and afterUpdate) that are automatically executed post-deployment.

Summary of Changes

1. Hook Registrations (`src/lifecycle/index.ts`)

Added new top-level entrypoints and types under firebase-functions/lifecycle:
- afterInstall(action: LifecycleAction): Registers a hook to run when resources in the codebase are deployed for the first time.
- afterUpdate(action: LifecycleAction): Registers a hook to run when resources in the codebase are updated.
Supported action types:
- task: Triggers a task queue function with an optional payload body.
- call: Calls a function (callable trigger) with optional params.
- http: Triggers a HTTP endpoint via request url/function, method, and body.
Ensures only one instance of afterInstall and afterUpdate can be registered per codebase at runtime.

2. Stack Manifest Parsing (`src/runtime/loader.ts`, `src/runtime/manifest.ts`)

Added ManifestLifecycleAction and updated ManifestStack types to include the lifecycleHooks field.
Updated loadStack inside loader.ts to capture any declared lifecycle hooks from global symbols during function discovery, mapping them into the compiled JSON/wire format returned to firebase-tools.
Updated stackToWire serialization helper to recursively resolve CEL expressions and reset values inside lifecycleHooks properties.

3. Tests

Created spec/lifecycle/lifecycle.spec.ts to test hook registration and duplicate hook prevention.
Added tests in spec/runtime/loader.spec.ts verifying that afterInstall and afterUpdate declarations are correctly discovered and serialized into the ManifestStack.

Code sample

export const runInitialSetup = onTaskDispatched(async (request) => {
  await performDatabaseSeeding(request.data);
});

// The CLI automatically discovers this call and queues the task after first-time deploy
afterInstall({
  task: {
    function: "runInitialSetup",
    body: { data: "default_catalog" }
  }
});

gemini-code-assist

Code Review

This pull request introduces support for post-deployment lifecycle hooks (afterInstall and afterUpdate) by adding a new lifecycle module, updating the manifest stack loader to capture these hooks, and exposing the module exports in package.json. The review feedback highlights a correctness issue in src/runtime/loader.ts where falsy but valid JSON values (such as 0 or false) are incorrectly omitted during serialization, and suggests using TypeScript union types in src/lifecycle/index.ts to enforce mutually exclusive properties at compile-time.

…e falsy body/params in loader

inlined

Don't forget that when we publish this it should also go in index.ts
You're going to need to add the fake empty file to avoid eslint problems (v2 not src/v2)

inlined

Sorry, forgot to set approve. I trust that this feedback is straightforward enough to fix if you also agree about the expression thing

* Clean up use of Expression<String> * Directly load from the manifest for hooks * Clean up HttpAction def * Add lifecycle to index.ts * Add empty index.js file for eslint

ajperel

Some mostly nitty comments after the fact as I review this PR to learn more than find issues. But still could be nice to address eventually. I could potentially send a PR myself if you prefer?

ajperel · 2026-07-01T22:14:08Z

+  | { call: CallAction; task?: never; http?: never }
+  | { http: HttpAction; task?: never; call?: never };
+
+const majorVersion =


I was definitely like "Why is this here and why do we need it?" I'd suggest having a nice comment like params/index.ts does to explain what's going on here.

ajperel · 2026-07-01T22:14:10Z

+  params?: Record<string, unknown>;
+}
+
+export type HttpAction = ({ function: string } | { url: string }) & {


Does the URL here need to accept string | Expression<string> similar to ManifestLifecycleAction below to fully support CEL expressions?

I missed updating ManifestLifecycleAction to only accept a string. None of these fields should be parameterized. I'll update this in a follow-up PR along with the documentation comment above.

ajperel · 2026-07-01T22:19:29Z

+  if (Object.keys(declaredLifecycleHooks).length > 0) {
+    stack.lifecycleHooks = { ...declaredLifecycleHooks };
+  }
+  clearDeclaredLifecycleHooks();


clearDeclaredLifecycleHooks() documentation said it was primarily for testing. Why do you need to call it here?

Seems like you do need it here similar to clearGlobalRequiredAPIs(); and maybe we should have a slightly different comment on the method itself. IF AI is correct because loadStack() will be called multiple times when reloading things for the emulator?

Hm, I can see how the "primarily for testing" bit can cause confusion since it's also used to clear the cache to avoid throwing errors about the hooks being already defined on subsequent loads. I'll remove that piece of the docstring in clearDeclaredLifecycleHooks in the follow-up PR.

…1929) # Description Fixes Cloud Build substitution errors when running prerelease/force deploys. Also had to change a GitHub repository setting to make sure the commit message is the PR description. The previous relnotes were lost and are added back here. # Release Notes relnote: fix: Remove false warning when using Expression in cors option (#1802) relnote: feat: Add requiresRole developer API for declarative security support and automatic Manifest extraction (#1908) relnote: Validate literal `timeoutSeconds` values per v2 trigger type (0-540s for events, 0-3600s for HTTPS/callable, 0-1800s for task queues, 0-7s for identity functions) so misconfigured values fail at function-definition or manifest-extraction time instead of at deploy time. (#1877) relnote: feat: Add requiresAPI function to allow declaring Google Cloud API dependencies in code. (#1900) relnote: fix(v1): Call onInit for schedule.onRun functions (#1801) relnote: feat: Add support to declare lifecycle hooks in functions. (#1915) relnote: fix(cors): Fix issue using Params to set CORS allowed hosts (#1903) relnote: fix(v2): Fix event data unpacking for auth event triggers (#1923) relnote: feat: Add "v2/lifecycle" and "lifecycle" import paths for lifecycle hooks (#1926) relnote: chore: revamp deploy pipeline to be stateless. Changes must now include relnotes relnote: chore: move the last encrypted keys into Google Cloud Secrets Manager

gemini-code-assist Bot reviewed Jun 25, 2026

View reviewed changes

Comment thread src/runtime/loader.ts Outdated

Comment thread src/lifecycle/index.ts Outdated

feature: functions can now declare lifecycle hooks

9489ef4

wandamora force-pushed the morawand-lifecycle-hook-api branch from 02d17b8 to 9489ef4 Compare June 25, 2026 20:06

refactor(lifecycle): improve type safety with union types and preserv…

49e9d1b

…e falsy body/params in loader

wandamora requested a review from inlined June 25, 2026 21:31

Add headers to HttpAction

55db1e1

inlined reviewed Jun 26, 2026

View reviewed changes

Comment thread src/lifecycle/index.ts Outdated

Comment thread src/lifecycle/index.ts Outdated

Comment thread src/runtime/loader.ts Outdated

inlined approved these changes Jun 26, 2026

View reviewed changes

wandamora added 2 commits June 26, 2026 17:35

Address comments

9af0464

* Clean up use of Expression<String> * Directly load from the manifest for hooks * Clean up HttpAction def * Add lifecycle to index.ts * Add empty index.js file for eslint

Add CHANGELOG

fd8840d

wandamora added this pull request to the merge queue Jun 26, 2026

Merged via the queue into master with commit 5e1d423 Jun 26, 2026
31 checks passed

ajperel reviewed Jul 1, 2026

View reviewed changes

This was referenced Jul 14, 2026

Revamp deploy pipeline to be stateless #1925

Merged

fix: resolve Cloud Build invalid argument errors for substitutions #1929

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feature: functions can now declare lifecycle hooks - #1915

feature: functions can now declare lifecycle hooks#1915
wandamora merged 5 commits into
masterfrom
morawand-lifecycle-hook-api

wandamora commented Jun 25, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Uh oh!

inlined left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

inlined left a comment

Uh oh!

Uh oh!

ajperel left a comment

Uh oh!

ajperel Jul 1, 2026

Uh oh!

ajperel Jul 1, 2026

Uh oh!

wandamora Jul 6, 2026

Uh oh!

ajperel Jul 1, 2026

Uh oh!

wandamora Jul 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

wandamora commented Jun 25, 2026

Description

Summary of Changes

1. Hook Registrations (src/lifecycle/index.ts)

2. Stack Manifest Parsing (src/runtime/loader.ts, src/runtime/manifest.ts)

3. Tests

Code sample

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

inlined left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

inlined left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ajperel left a comment

Choose a reason for hiding this comment

Uh oh!

ajperel Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

ajperel Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

wandamora Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

ajperel Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

wandamora Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

1. Hook Registrations (`src/lifecycle/index.ts`)

2. Stack Manifest Parsing (`src/runtime/loader.ts`, `src/runtime/manifest.ts`)