From 496ed2bf27dc529adf96268bae3c08f34e18b7ce Mon Sep 17 00:00:00 2001 From: Jeff Huleatt <3759507+jhuleatt@users.noreply.github.com> Date: Fri, 20 Feb 2026 11:04:52 -0500 Subject: [PATCH 1/6] add a CF3 skill --- skills/firebase-cloud-functions/SKILL.md | 87 +++++++++ .../references/node_setup.md | 69 +++++++ .../references/python_setup.md | 84 +++++++++ .../references/upgrade.md | 178 ++++++++++++++++++ 4 files changed, 418 insertions(+) create mode 100644 skills/firebase-cloud-functions/SKILL.md create mode 100644 skills/firebase-cloud-functions/references/node_setup.md create mode 100644 skills/firebase-cloud-functions/references/python_setup.md create mode 100644 skills/firebase-cloud-functions/references/upgrade.md diff --git a/skills/firebase-cloud-functions/SKILL.md b/skills/firebase-cloud-functions/SKILL.md new file mode 100644 index 0000000..4deaadd --- /dev/null +++ b/skills/firebase-cloud-functions/SKILL.md @@ -0,0 +1,87 @@ +--- +name: firebase-cloud-functions +description: Guide for setting up and using Cloud Functions for Firebase. Use this skill when the user's app requires server-side logic, integrating with third-party APIs, or responding to Firebase events. +compatibility: This skill requires the Firebase CLI. Install it by running `npm install -g firebase-tools`. +--- + +## Prerequisites + +- **Firebase Project**: Created via `firebase projects:create` (see `firebase-basics`). +- **Firebase CLI**: Installed and logged in (see `firebase-basics`). + +## Core Concepts + +Cloud Functions for Firebase lets you automatically run backend code in response to events triggered by Firebase features and HTTPS requests. Your code is stored in Google's cloud and runs in a managed environment. + +### Generation 1 vs Generation 2 + +This section only applies to Node.js, since all Python functions are 2nd gen. + +- Always use 2nd-gen functions for new development. They are powered by Cloud Run and offer better performance and configurability. +- Use 1st-gen functions *only* for Analytics and basic Auth triggers, since those aren't supported by 2nd gen. +- Use `firebase-functions` SDK version 6.0.0 and above. +- Use top-level imports (e.g., `firebase-functions/https`). These are 2nd gen by default. If 1st gen is required (Analytics or basic Auth triggers), import from the `firebase-functions/v1` import path. + +### Secrets Management + +For sensitive information like API keys (e.g., for LLMs, payment providers, etc.), **always** use `defineSecret` (Node.js) or `SecretParam` (Python). This stores the value securely in Cloud Secret Manager. + +If you see an API key being accessed with `functions.config` in existing functions code, offer to upgrade to params. + +### Firebase Admin SDK + +To interact with Firebase services like Firestore, Auth, or RTDB from within your functions, you need to initialize the Firebase Admin SDK. Call `initializeApp` without any arguments so that Application Default Credentials are used. + +## Workflow + +### 1. Provisioning & Setup + +Functions can be initialized using the CLI or manually. Ensure you have initialized the Firebase Admin SDK to interact with other Firebase services. + +1. **Install the Admin SDK:** + + ```bash + npm i firebase-admin + ``` + +2. **Initialize in your code:** + + ```typescript + import * as admin from "firebase-admin"; + import { onInit } from "firebase-functions"; + + onInit(() => { + admin.initializeApp(); + }); + ``` + + This should be done once at the top level of your `index.ts` file. + +### 2. Writing Functions + +For Node.js, see [references/node_setup.md](references/node_setup.md). For Python, see [references/python_setup.md](references/python_setup.md) + +### 3. Local Development & Deployment + +The CLI will prompt for secret's value at deploy time. Alternatively, a human can set the secret using the Firebase CLI command: + +```bash +firebase functions:secrets:set +``` + +#### Development Commands + +```bash +# Install dependencies +npm install + +# Compile TypeScript +npm run build + +# Run emulators for local development +# This is a long-running command. A human can run this command themselves to start the emulators: +firebase emulators:start --only functions + +# Deploy functions +firebase deploy --only functions +``` \ No newline at end of file diff --git a/skills/firebase-cloud-functions/references/node_setup.md b/skills/firebase-cloud-functions/references/node_setup.md new file mode 100644 index 0000000..f98c405 --- /dev/null +++ b/skills/firebase-cloud-functions/references/node_setup.md @@ -0,0 +1,69 @@ +# Cloud Functions for Firebase setup guide + +This guide provides a step-by-step process for setting up Cloud Functions, tailored for coding agents. + +## 1. Create a 2nd-gen HTTP function + +Replace the contents of `src/index.ts` (or `index.js`) with the following code to create a simple, modern v2 HTTP endpoint. + +```typescript +import { onRequest } from "firebase-functions/https"; +import { onDocumentCreated } from "firebase-functions/firestore"; +import * as logger from "firebase-functions/logger"; +import { defineString, defineInt } from "firebase-functions/params"; + +// Configurable parameters +const scaleLimit = defineInt("MAX_INSTANCES", { default: 1 }); +const greeting = defineString("GREETING", { default: "Hello" }); + +export const helloWorld = onRequest({ maxInstances: scaleLimit }, async (request, response) => { + logger.info("Request received!", request); + response.send(`${greeting.value()} from Firebase!`); +}); + +export const newDoc = onDocumentCreated( + { maxInstances: scaleLimit }, + "/words/{wordId}", + async (event) => { + logger.info("New word!", event.data.data()); + } +); +``` + +**Key points for the agent:** + +- Use `logger` for structured logging. +- Use `defineString`, `defineInt`, `defineSecret` for environment configuration instead of `functions.config()`. +- Recommend a `maxInstances` setting of 1 for all functions until correct behavior can be verified. + +## 2. Build TypeScript + +Compile your TypeScript code to JavaScript. + +```bash +npm run build +``` + +## 3. Local Development and Testing + +Use the Firebase Emulators to test your function locally before deploying. + +A human should run the following command in a separate terminal window to start the emulators: + +```bash +# Start the functions emulator +firebase emulators:start --only functions +``` + +A human can then interact with the function at the local URL provided by the emulator. + +## 4. Deploy to Firebase + +Once testing is complete, deploy the function to your Firebase project. + +```bash +# Deploy only the functions +firebase deploy --only functions +``` + +The agent will be prompted to set any parameters defined with `defineString` or other `define` functions that do not have a default value. \ No newline at end of file diff --git a/skills/firebase-cloud-functions/references/python_setup.md b/skills/firebase-cloud-functions/references/python_setup.md new file mode 100644 index 0000000..ea1ffd9 --- /dev/null +++ b/skills/firebase-cloud-functions/references/python_setup.md @@ -0,0 +1,84 @@ +# Cloud Functions for Firebase setup guide (Python) + +This guide provides a step-by-step process for setting up Cloud Functions with the Python runtime, tailored for coding agents. + +## 1. Create a 2nd-gen HTTP function + +Replace the contents of `functions/main.py` with the following code to create a simple, modern v2 HTTP endpoint along with a Firestore-triggered function. + +```python +from firebase_functions import https_fn, firestore_fn, options, params +from firebase_admin import initialize_app, firestore +import google.cloud.firestore + +app = initialize_app() + +# Configurable parameters +SCALE_LIMIT = params.IntParam("MAX_INSTANCES", default=1).value +GREETING = params.StringParam("GREETING", default="Hello").value + + +@https_fn.on_request( + cors=options.CorsOptions(cors_origins="*", cors_methods=["get", "post"]), + max_instances=SCALE_LIMIT, +) +def helloworld(req: https_fn.Request) -> https_fn.Response: + """A simple HTTP-triggered function.""" + print("Request received!") + return https_fn.Response(f"{GREETING} from Firebase!") + + +@firestore_fn.on_document_created(document="words/{wordId}", max_instances=SCALE_LIMIT) +def newdoc(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None: + """Triggered when a new document is created in /words.""" + if event.data is None: + return + print(f"New word: {event.data.to_dict()}") +``` + +**Key points for the agent:** + +- Use `print()` for logging (output goes to Cloud Logging automatically). +- Use `params.StringParam`, `params.IntParam`, and `params.SecretParam` for environment configuration. +- Recommend a `max_instances` setting of 1 for all functions until correct behavior can be verified. +- The entry point is always `functions/main.py`. All functions must be defined in or imported into this file. +- Dependencies go in `functions/requirements.txt`. + +## 2. Install dependencies + +Ensure `functions/requirements.txt` lists the needed packages: + +``` +firebase-functions +firebase-admin +``` + +Then install with: + +```bash +pip install -r functions/requirements.txt +``` + +There is no build step for Python (unlike TypeScript). + +## 3. Local Development and Testing + +Use the Firebase Emulators to test your function locally before deploying. + +A human should run the following command in a separate terminal window to start the emulators: + +```bash +# Start the functions emulator +firebase emulators:start --only functions +``` + +A human can then interact with the function at the local URL provided by the emulator. + +## 4. Deploy to Firebase + +Once testing is complete, deploy the function to your Firebase project. + +```bash +# Deploy only the functions +firebase deploy --only functions +``` diff --git a/skills/firebase-cloud-functions/references/upgrade.md b/skills/firebase-cloud-functions/references/upgrade.md new file mode 100644 index 0000000..bffdfa4 --- /dev/null +++ b/skills/firebase-cloud-functions/references/upgrade.md @@ -0,0 +1,178 @@ +# Upgrading a 1st gen function to 2nd gen + +This guide provides a step-by-step process for migrating a single Cloud Function from 1st to 2nd generation. Migrate functions one-by-one. Run both generations side-by-side before deleting the 1st gen function. + +## 1. Identify a 1st-gen function to upgrade + +Find all 1st-gen functions in the directory. 1st-gen functions used a namespaced API like this: + +**Before (1st Gen):** + +```typescript +import * as functions from "firebase-functions"; + +export const webhook = functions.https.onRequest((request, response) => { + // ... +}); +``` + +Sometimes, they'll explicitly import from the `firebase-functions/v1` subpackage, but not always. + +Ask the human to pick a **single** function to upgrade from the list of 1st gen functions you found. + +## 2. Update Dependencies + +Ensure your `firebase-functions` and `firebase-admin` SDKs are up-to-date, and you are using a recent version of the Firebase CLI. + +## 3. Modify Imports + +Update your import statements to use the top-level modules. + +**After (2nd Gen):** + +```typescript +import { onRequest } from "firebase-functions/https"; +``` + +## 4. Update Trigger Definition + +The SDK is now more modular. Update your trigger definition accordingly. + +**After (2nd Gen):** + +```typescript +export const webhook = onRequest((request, response) => { + // ... +}); +``` + +Here are other examples of trigger changes: + +### Callable Triggers + +**Before (1st Gen):** + +```typescript +export const getprofile = functions.https.onCall((data, context) => { + // ... +}); +``` + +**After (2nd Gen):** + +```typescript +import { onCall } from "firebase-functions/https"; + +export const getprofile = onCall((request) => { + // ... +}); +``` + +### Background Triggers (Pub/Sub) + +**Before (1st Gen):** + +```typescript +export const hellopubsub = functions.pubsub.topic("topic-name").onPublish((message) => { + // ... +}); +``` + +**After (2nd Gen):** + +```typescript +import { onMessagePublished } from "firebase-functions/pubsub"; + +export const hellopubsub = onMessagePublished("topic-name", (event) => { + // ... +}); +``` + +## 5. Use Parameterized Configuration + +Migrate from `functions.config()` to the new `params` module for environment configuration. + +**Before (`.runtimeconfig.json`):** + +```json +{ + "someservice": { + "key": "somesecret" + } +} +``` + +**And in code (1st Gen):** + +```typescript +const SKEY = functions.config().someservice.key; +``` + +**After (2nd Gen):** +Define params in your code and set their values during deployment. + +**In `index.ts`:** + +```typescript +import { defineString } from "firebase-functions/params"; + +const SOMESERVICE_KEY = defineString("SOMESERVICE_KEY"); +``` + +Use `SOMESERVICE_KEY.value()` to access the value. For secrets like API keys, use `defineSecret`. + +**In `index.ts`:** + +```typescript +import { defineSecret } from "firebase-functions/params"; + +const SOMESERVICE_KEY = defineSecret("SOMESERVICE_KEY"); +``` + +The human will be prompted to set the value on deployment. The value will be stored securely in Cloud Secret Manager. + +## 6. Update Runtime Options + +Runtime options are now set directly within the function definition. + +**Before (1st Gen):** + +```typescript +export const func = functions + .runWith({ + // Keep 5 instances warm + minInstances: 5, + }) + .https.onRequest((request, response) => { + // ... + }); +``` + +**After (2nd Gen):** + +```typescript +import { onRequest } from "firebase-functions/https"; + +export const func = onRequest( + { + // Keep 5 instances warm + minInstances: 5, + }, + (request, response) => { + // ... + } +); +``` + +## 7. Traffic Migration + +A human should follow these steps to migrate safely: + +> To migrate traffic safely: +> +> 1. Rename your new 2nd gen function with a different name. +> 2. Comment out any existing `minInstances` or `maxInstances` config in the new 2nd gen function and instead set `maxInstances` to `1` while testing. +> 3. Deploy it alongside the old 1st gen function. +> 4. Gradually introduce traffic to the new function (e.g., via client-side changes or by calling it from the 1st gen function). +> 5. As traffic ramps up to the new 2nd gen function, scale it up by adding back the original `minInstances` and `maxInstances` settings to the 2nd gen function. Reduce the `minInstances` and `maxInstances` settings for the 1st gen function as traffic decreases. +> 6. The 1st gen function can be deleted once it has stopped receiving traffic. \ No newline at end of file From f65ab012facceb378ff500358c04d6160b26c32d Mon Sep 17 00:00:00 2001 From: Jeff Huleatt <3759507+jhuleatt@users.noreply.github.com> Date: Tue, 24 Feb 2026 13:33:04 -0500 Subject: [PATCH 2/6] use modular Admin SDK import --- skills/firebase-cloud-functions/SKILL.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/skills/firebase-cloud-functions/SKILL.md b/skills/firebase-cloud-functions/SKILL.md index 4deaadd..9d4beef 100644 --- a/skills/firebase-cloud-functions/SKILL.md +++ b/skills/firebase-cloud-functions/SKILL.md @@ -38,20 +38,20 @@ To interact with Firebase services like Firestore, Auth, or RTDB from within you Functions can be initialized using the CLI or manually. Ensure you have initialized the Firebase Admin SDK to interact with other Firebase services. -1. **Install the Admin SDK:** +1. Install the Admin SDK: ```bash npm i firebase-admin ``` -2. **Initialize in your code:** +2. Initialize in your code: ```typescript - import * as admin from "firebase-admin"; + import { initializeApp } from "firebase-admin/app"; import { onInit } from "firebase-functions"; onInit(() => { - admin.initializeApp(); + initializeApp(); }); ``` From 0075f470ee2bda483e2a8aedb3797f0842364980 Mon Sep 17 00:00:00 2001 From: Jeff Huleatt <3759507+jhuleatt@users.noreply.github.com> Date: Tue, 24 Feb 2026 13:33:35 -0500 Subject: [PATCH 3/6] change upgrade instructions to use new defineJsonSecret flow --- skills/firebase-cloud-functions/SKILL.md | 4 +- .../references/upgrade.md | 76 +++++++++++-------- 2 files changed, 46 insertions(+), 34 deletions(-) diff --git a/skills/firebase-cloud-functions/SKILL.md b/skills/firebase-cloud-functions/SKILL.md index 9d4beef..9fc1431 100644 --- a/skills/firebase-cloud-functions/SKILL.md +++ b/skills/firebase-cloud-functions/SKILL.md @@ -26,7 +26,7 @@ This section only applies to Node.js, since all Python functions are 2nd gen. For sensitive information like API keys (e.g., for LLMs, payment providers, etc.), **always** use `defineSecret` (Node.js) or `SecretParam` (Python). This stores the value securely in Cloud Secret Manager. -If you see an API key being accessed with `functions.config` in existing functions code, offer to upgrade to params. +If you see an API key being accessed with `functions.config` in existing functions code, offer to [upgrade to params](references/upgrade.md). ### Firebase Admin SDK @@ -63,7 +63,7 @@ For Node.js, see [references/node_setup.md](references/node_setup.md). For Pytho ### 3. Local Development & Deployment -The CLI will prompt for secret's value at deploy time. Alternatively, a human can set the secret using the Firebase CLI command: +The CLI will prompt for a secret's value at deploy time. Alternatively, a human can set the secret using the Firebase CLI command: ```bash firebase functions:secrets:set diff --git a/skills/firebase-cloud-functions/references/upgrade.md b/skills/firebase-cloud-functions/references/upgrade.md index bffdfa4..a7a047e 100644 --- a/skills/firebase-cloud-functions/references/upgrade.md +++ b/skills/firebase-cloud-functions/references/upgrade.md @@ -90,46 +90,60 @@ export const hellopubsub = onMessagePublished("topic-name", (event) => { ## 5. Use Parameterized Configuration -Migrate from `functions.config()` to the new `params` module for environment configuration. +The `functions.config` API is deprecated and will be decommissioned in March 2027. 2nd gen functions drop support for `functions.config` in favor of a more secure interface for defining configuration parameters declaratively inside your codebase. -**Before (`.runtimeconfig.json`):** +To migrate your configuration to Cloud Secret Manager, use the Firebase CLI: -```json -{ - "someservice": { - "key": "somesecret" - } -} -``` +### 1. Export configuration with the Firebase CLI -**And in code (1st Gen):** +Use the config export command to interactively export your existing environment config to a new secret in Cloud Secret Manager: -```typescript -const SKEY = functions.config().someservice.key; +```bash +firebase functions:config:export ``` -**After (2nd Gen):** -Define params in your code and set their values during deployment. +### 2. Update function code to bind secrets -**In `index.ts`:** +To use configuration stored in the new secret in Cloud Secret Manager, use the `defineJsonSecret` API in your function source. Make sure that secrets are bound to all functions that need them. + +**Before (1st Gen):** ```typescript -import { defineString } from "firebase-functions/params"; +import * as functions from "firebase-functions"; -const SOMESERVICE_KEY = defineString("SOMESERVICE_KEY"); +export const myFunction = functions.https.onRequest((req, res) => { + const apiKey = functions.config().someapi.key; + // ... +}); ``` -Use `SOMESERVICE_KEY.value()` to access the value. For secrets like API keys, use `defineSecret`. - -**In `index.ts`:** +**After (2nd Gen):** ```typescript -import { defineSecret } from "firebase-functions/params"; - -const SOMESERVICE_KEY = defineSecret("SOMESERVICE_KEY"); +import { onRequest } from "firebase-functions/v2/https"; +import { defineJsonSecret } from "firebase-functions/params"; + +// RUNTIME_CONFIG is the default name set by the `firebase functions:config:export` command +const config = defineJsonSecret("RUNTIME_CONFIG"); + +export const myFunction = onRequest( + // Bind secret to your function + { secrets: [config] }, + (req, res) => { + // Access secret values via .value() + const apiKey = config.value().someapi.key; + // ... + } +); ``` -The human will be prompted to set the value on deployment. The value will be stored securely in Cloud Secret Manager. +### 3. Deploy Functions + +Deploy your updated functions to apply the changes and bind the secret permissions. + +```bash +firebase deploy --only functions: +``` ## 6. Update Runtime Options @@ -168,11 +182,9 @@ export const func = onRequest( A human should follow these steps to migrate safely: -> To migrate traffic safely: -> -> 1. Rename your new 2nd gen function with a different name. -> 2. Comment out any existing `minInstances` or `maxInstances` config in the new 2nd gen function and instead set `maxInstances` to `1` while testing. -> 3. Deploy it alongside the old 1st gen function. -> 4. Gradually introduce traffic to the new function (e.g., via client-side changes or by calling it from the 1st gen function). -> 5. As traffic ramps up to the new 2nd gen function, scale it up by adding back the original `minInstances` and `maxInstances` settings to the 2nd gen function. Reduce the `minInstances` and `maxInstances` settings for the 1st gen function as traffic decreases. -> 6. The 1st gen function can be deleted once it has stopped receiving traffic. \ No newline at end of file +1. Rename your new 2nd gen function with a different name. +2. Comment out any existing `minInstances` or `maxInstances` config in the new 2nd gen function and instead set `maxInstances` to `1` while testing. +3. Deploy it alongside the old 1st gen function. +4. Gradually introduce traffic to the new function (e.g., via client-side changes or by calling it from the 1st gen function). +5. As traffic ramps up to the new 2nd gen function, scale it up by adding back the original `minInstances` and `maxInstances` settings to the 2nd gen function. Reduce the `minInstances` and `maxInstances` settings for the 1st gen function as traffic decreases. +6. The 1st gen function can be deleted once it has stopped receiving traffic. \ No newline at end of file From 628dd86a847f3c142b85eed1baa47c6c4a203121 Mon Sep 17 00:00:00 2001 From: Jeff Huleatt <3759507+jhuleatt@users.noreply.github.com> Date: Tue, 24 Feb 2026 16:25:49 -0500 Subject: [PATCH 4/6] rename to cloud-functions-basics --- .../SKILL.md | 2 +- .../references/node_setup.md | 0 .../references/python_setup.md | 0 .../references/upgrade.md | 0 4 files changed, 1 insertion(+), 1 deletion(-) rename skills/{firebase-cloud-functions => cloud-functions-basics}/SKILL.md (99%) rename skills/{firebase-cloud-functions => cloud-functions-basics}/references/node_setup.md (100%) rename skills/{firebase-cloud-functions => cloud-functions-basics}/references/python_setup.md (100%) rename skills/{firebase-cloud-functions => cloud-functions-basics}/references/upgrade.md (100%) diff --git a/skills/firebase-cloud-functions/SKILL.md b/skills/cloud-functions-basics/SKILL.md similarity index 99% rename from skills/firebase-cloud-functions/SKILL.md rename to skills/cloud-functions-basics/SKILL.md index 9fc1431..26b4eaa 100644 --- a/skills/firebase-cloud-functions/SKILL.md +++ b/skills/cloud-functions-basics/SKILL.md @@ -1,5 +1,5 @@ --- -name: firebase-cloud-functions +name: firebase-functions-basics description: Guide for setting up and using Cloud Functions for Firebase. Use this skill when the user's app requires server-side logic, integrating with third-party APIs, or responding to Firebase events. compatibility: This skill requires the Firebase CLI. Install it by running `npm install -g firebase-tools`. --- diff --git a/skills/firebase-cloud-functions/references/node_setup.md b/skills/cloud-functions-basics/references/node_setup.md similarity index 100% rename from skills/firebase-cloud-functions/references/node_setup.md rename to skills/cloud-functions-basics/references/node_setup.md diff --git a/skills/firebase-cloud-functions/references/python_setup.md b/skills/cloud-functions-basics/references/python_setup.md similarity index 100% rename from skills/firebase-cloud-functions/references/python_setup.md rename to skills/cloud-functions-basics/references/python_setup.md diff --git a/skills/firebase-cloud-functions/references/upgrade.md b/skills/cloud-functions-basics/references/upgrade.md similarity index 100% rename from skills/firebase-cloud-functions/references/upgrade.md rename to skills/cloud-functions-basics/references/upgrade.md From 5b0dab9b1c8ee97f7b28be95a3584532f24baea9 Mon Sep 17 00:00:00 2001 From: Jeff Huleatt <3759507+jhuleatt@users.noreply.github.com> Date: Tue, 24 Feb 2026 17:05:50 -0500 Subject: [PATCH 5/6] rename to firebase-functions-basics --- .../SKILL.md | 0 .../references/node_setup.md | 0 .../references/python_setup.md | 0 .../references/upgrade.md | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename skills/{cloud-functions-basics => firebase-functions-basics}/SKILL.md (100%) rename skills/{cloud-functions-basics => firebase-functions-basics}/references/node_setup.md (100%) rename skills/{cloud-functions-basics => firebase-functions-basics}/references/python_setup.md (100%) rename skills/{cloud-functions-basics => firebase-functions-basics}/references/upgrade.md (100%) diff --git a/skills/cloud-functions-basics/SKILL.md b/skills/firebase-functions-basics/SKILL.md similarity index 100% rename from skills/cloud-functions-basics/SKILL.md rename to skills/firebase-functions-basics/SKILL.md diff --git a/skills/cloud-functions-basics/references/node_setup.md b/skills/firebase-functions-basics/references/node_setup.md similarity index 100% rename from skills/cloud-functions-basics/references/node_setup.md rename to skills/firebase-functions-basics/references/node_setup.md diff --git a/skills/cloud-functions-basics/references/python_setup.md b/skills/firebase-functions-basics/references/python_setup.md similarity index 100% rename from skills/cloud-functions-basics/references/python_setup.md rename to skills/firebase-functions-basics/references/python_setup.md diff --git a/skills/cloud-functions-basics/references/upgrade.md b/skills/firebase-functions-basics/references/upgrade.md similarity index 100% rename from skills/cloud-functions-basics/references/upgrade.md rename to skills/firebase-functions-basics/references/upgrade.md From addcf4c1cab68a42c70a35549f88a97969e2795c Mon Sep 17 00:00:00 2001 From: Jeff Huleatt <3759507+jhuleatt@users.noreply.github.com> Date: Wed, 25 Feb 2026 16:09:36 -0500 Subject: [PATCH 6/6] remove upgrade guide and all references to functions.config --- skills/firebase-functions-basics/SKILL.md | 2 - .../references/node_setup.md | 2 +- .../references/upgrade.md | 190 ------------------ 3 files changed, 1 insertion(+), 193 deletions(-) delete mode 100644 skills/firebase-functions-basics/references/upgrade.md diff --git a/skills/firebase-functions-basics/SKILL.md b/skills/firebase-functions-basics/SKILL.md index 26b4eaa..5e216a1 100644 --- a/skills/firebase-functions-basics/SKILL.md +++ b/skills/firebase-functions-basics/SKILL.md @@ -26,8 +26,6 @@ This section only applies to Node.js, since all Python functions are 2nd gen. For sensitive information like API keys (e.g., for LLMs, payment providers, etc.), **always** use `defineSecret` (Node.js) or `SecretParam` (Python). This stores the value securely in Cloud Secret Manager. -If you see an API key being accessed with `functions.config` in existing functions code, offer to [upgrade to params](references/upgrade.md). - ### Firebase Admin SDK To interact with Firebase services like Firestore, Auth, or RTDB from within your functions, you need to initialize the Firebase Admin SDK. Call `initializeApp` without any arguments so that Application Default Credentials are used. diff --git a/skills/firebase-functions-basics/references/node_setup.md b/skills/firebase-functions-basics/references/node_setup.md index f98c405..2ca6dcd 100644 --- a/skills/firebase-functions-basics/references/node_setup.md +++ b/skills/firebase-functions-basics/references/node_setup.md @@ -33,7 +33,7 @@ export const newDoc = onDocumentCreated( **Key points for the agent:** - Use `logger` for structured logging. -- Use `defineString`, `defineInt`, `defineSecret` for environment configuration instead of `functions.config()`. +- Use `defineString`, `defineInt`, `defineSecret` for environment configuration. - Recommend a `maxInstances` setting of 1 for all functions until correct behavior can be verified. ## 2. Build TypeScript diff --git a/skills/firebase-functions-basics/references/upgrade.md b/skills/firebase-functions-basics/references/upgrade.md deleted file mode 100644 index a7a047e..0000000 --- a/skills/firebase-functions-basics/references/upgrade.md +++ /dev/null @@ -1,190 +0,0 @@ -# Upgrading a 1st gen function to 2nd gen - -This guide provides a step-by-step process for migrating a single Cloud Function from 1st to 2nd generation. Migrate functions one-by-one. Run both generations side-by-side before deleting the 1st gen function. - -## 1. Identify a 1st-gen function to upgrade - -Find all 1st-gen functions in the directory. 1st-gen functions used a namespaced API like this: - -**Before (1st Gen):** - -```typescript -import * as functions from "firebase-functions"; - -export const webhook = functions.https.onRequest((request, response) => { - // ... -}); -``` - -Sometimes, they'll explicitly import from the `firebase-functions/v1` subpackage, but not always. - -Ask the human to pick a **single** function to upgrade from the list of 1st gen functions you found. - -## 2. Update Dependencies - -Ensure your `firebase-functions` and `firebase-admin` SDKs are up-to-date, and you are using a recent version of the Firebase CLI. - -## 3. Modify Imports - -Update your import statements to use the top-level modules. - -**After (2nd Gen):** - -```typescript -import { onRequest } from "firebase-functions/https"; -``` - -## 4. Update Trigger Definition - -The SDK is now more modular. Update your trigger definition accordingly. - -**After (2nd Gen):** - -```typescript -export const webhook = onRequest((request, response) => { - // ... -}); -``` - -Here are other examples of trigger changes: - -### Callable Triggers - -**Before (1st Gen):** - -```typescript -export const getprofile = functions.https.onCall((data, context) => { - // ... -}); -``` - -**After (2nd Gen):** - -```typescript -import { onCall } from "firebase-functions/https"; - -export const getprofile = onCall((request) => { - // ... -}); -``` - -### Background Triggers (Pub/Sub) - -**Before (1st Gen):** - -```typescript -export const hellopubsub = functions.pubsub.topic("topic-name").onPublish((message) => { - // ... -}); -``` - -**After (2nd Gen):** - -```typescript -import { onMessagePublished } from "firebase-functions/pubsub"; - -export const hellopubsub = onMessagePublished("topic-name", (event) => { - // ... -}); -``` - -## 5. Use Parameterized Configuration - -The `functions.config` API is deprecated and will be decommissioned in March 2027. 2nd gen functions drop support for `functions.config` in favor of a more secure interface for defining configuration parameters declaratively inside your codebase. - -To migrate your configuration to Cloud Secret Manager, use the Firebase CLI: - -### 1. Export configuration with the Firebase CLI - -Use the config export command to interactively export your existing environment config to a new secret in Cloud Secret Manager: - -```bash -firebase functions:config:export -``` - -### 2. Update function code to bind secrets - -To use configuration stored in the new secret in Cloud Secret Manager, use the `defineJsonSecret` API in your function source. Make sure that secrets are bound to all functions that need them. - -**Before (1st Gen):** - -```typescript -import * as functions from "firebase-functions"; - -export const myFunction = functions.https.onRequest((req, res) => { - const apiKey = functions.config().someapi.key; - // ... -}); -``` - -**After (2nd Gen):** - -```typescript -import { onRequest } from "firebase-functions/v2/https"; -import { defineJsonSecret } from "firebase-functions/params"; - -// RUNTIME_CONFIG is the default name set by the `firebase functions:config:export` command -const config = defineJsonSecret("RUNTIME_CONFIG"); - -export const myFunction = onRequest( - // Bind secret to your function - { secrets: [config] }, - (req, res) => { - // Access secret values via .value() - const apiKey = config.value().someapi.key; - // ... - } -); -``` - -### 3. Deploy Functions - -Deploy your updated functions to apply the changes and bind the secret permissions. - -```bash -firebase deploy --only functions: -``` - -## 6. Update Runtime Options - -Runtime options are now set directly within the function definition. - -**Before (1st Gen):** - -```typescript -export const func = functions - .runWith({ - // Keep 5 instances warm - minInstances: 5, - }) - .https.onRequest((request, response) => { - // ... - }); -``` - -**After (2nd Gen):** - -```typescript -import { onRequest } from "firebase-functions/https"; - -export const func = onRequest( - { - // Keep 5 instances warm - minInstances: 5, - }, - (request, response) => { - // ... - } -); -``` - -## 7. Traffic Migration - -A human should follow these steps to migrate safely: - -1. Rename your new 2nd gen function with a different name. -2. Comment out any existing `minInstances` or `maxInstances` config in the new 2nd gen function and instead set `maxInstances` to `1` while testing. -3. Deploy it alongside the old 1st gen function. -4. Gradually introduce traffic to the new function (e.g., via client-side changes or by calling it from the 1st gen function). -5. As traffic ramps up to the new 2nd gen function, scale it up by adding back the original `minInstances` and `maxInstances` settings to the 2nd gen function. Reduce the `minInstances` and `maxInstances` settings for the 1st gen function as traffic decreases. -6. The 1st gen function can be deleted once it has stopped receiving traffic. \ No newline at end of file