Skip to content

Commit 94fdcef

Browse files
jhuleattjhuleatt
committed
gemini cli-assisted first-pass
1 parent 5e2c5f8 commit 94fdcef

File tree

5 files changed

+332
-0
lines changed

5 files changed

+332
-0
lines changed

‎.guides/config.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"description": "A set of guides for Cloud Functions for Firebase.",
3+
"mcpServers": {
4+
"firebase": {
5+
"command": "firebase",
6+
"args": ["mcp:server"]
7+
}
8+
}
9+
}

‎.guides/examples/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Firebase Functions Samples
2+
3+
For useful and minimal samples for various function triggers, please refer to the official Firebase Functions quickstarts repository on GitHub:
4+
5+
[https://github.com/firebase/functions-samples/tree/main/Node/quickstarts](https://github.com/firebase/functions-samples/tree/main/Node/quickstarts)

‎.guides/setup.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Firebase Functions Setup Guide
2+
3+
This guide provides a step-by-step process for setting up a new Firebase Functions project, tailored for a coding agent.
4+
5+
### **Step 1: Initialize Firebase Project**
6+
7+
If you haven't already, initialize your Firebase project. The agent should have the `firebase-tools` CLI installed.
8+
9+
```bash
10+
# One-time setup for a new project
11+
firebase login
12+
firebase init functions
13+
```
14+
During initialization, select `TypeScript`.
15+
16+
### **Step 2: Install Dependencies**
17+
18+
Navigate to the `functions` directory and install the necessary NPM packages.
19+
20+
```bash
21+
cd functions
22+
npm install
23+
```
24+
25+
### **Step 3: Create a v2 HTTP Function**
26+
27+
Replace the contents of `src/index.ts` with the following code to create a simple, modern v2 HTTP endpoint.
28+
29+
```typescript
30+
import {onRequest} from "firebase-functions/v2/https";
31+
import * as logger from "firebase-functions/logger";
32+
import {defineString} from "firebase-functions/params";
33+
34+
// Define a configuration parameter for a greeting
35+
const greeting = defineString("GREETING", {default: "Hello"});
36+
37+
export const helloWorld = onRequest((request, response) => {
38+
logger.info("Request received!", {structuredData: true});
39+
response.send(`${greeting.value()} from Firebase!`);
40+
});
41+
```
42+
43+
**Key points for the agent:**
44+
* Always import from `firebase-functions/v2/*` for new functions.
45+
* Use `logger` for structured logging.
46+
* Use `defineString`, `defineInt`, `defineSecret` for environment configuration instead of `functions.config()`.
47+
48+
### **Step 4: Build TypeScript**
49+
50+
Compile your TypeScript code to JavaScript.
51+
52+
```bash
53+
npm run build
54+
```
55+
56+
### **Step 5: Local Development and Testing**
57+
58+
Use the Firebase Emulators to test your function locally before deploying.
59+
60+
```bash
61+
# Start the functions emulator
62+
firebase emulators:start --only functions
63+
```
64+
The agent can then interact with the function at the local URL provided by the emulator.
65+
66+
### **Step 6: Deploy to Firebase**
67+
68+
Once testing is complete, deploy the function to your Firebase project.
69+
70+
```bash
71+
# Deploy only the functions
72+
firebase deploy --only functions
73+
```
74+
The agent will be prompted to set any parameters defined with `defineString` or other `define` functions that do not have a default value.

‎.guides/upgrade.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Upgrading Firebase Functions to 2nd Gen
2+
3+
This guide summarizes the process of migrating Cloud Functions from 1st to 2nd generation. You can migrate functions incrementally, running both generations side-by-side.
4+
5+
## 1. Update Dependencies
6+
7+
Update your `firebase-functions` and `firebase-admin` SDKs, and ensure you are using a recent version of the Firebase CLI.
8+
9+
## 2. Modify Imports
10+
11+
Update your import statements to use the `v2` subpackage.
12+
13+
**Before (1st Gen):**
14+
```typescript
15+
import * as functions from "firebase-functions";
16+
```
17+
18+
**After (2nd Gen):**
19+
```typescript
20+
import * as functions from "firebase-functions/v2";
21+
```
22+
23+
## 3. Update Trigger Definitions
24+
25+
The SDK is now more modular. Update your trigger definitions accordingly.
26+
27+
### HTTP Triggers
28+
29+
**Before (1st Gen):**
30+
```typescript
31+
export const webhook = functions.https.onRequest((request, response) => {
32+
// ...
33+
});
34+
```
35+
36+
**After (2nd Gen):**
37+
```typescript
38+
import {onRequest} from "firebase-functions/v2/https";
39+
40+
export const webhook = onRequest((request, response) => {
41+
// ...
42+
});
43+
```
44+
45+
### Callable Triggers
46+
47+
**Before (1st Gen):**
48+
```typescript
49+
export const getprofile = functions.https.onCall((data, context) => {
50+
// ...
51+
});
52+
```
53+
54+
**After (2nd Gen):**
55+
```typescript
56+
import {onCall} from "firebase-functions/v2/https";
57+
58+
export const getprofile = onCall((request) => {
59+
// ...
60+
});
61+
```
62+
63+
### Background Triggers (Pub/Sub)
64+
65+
**Before (1st Gen):**
66+
```typescript
67+
export consthellopubsub = functions.pubsub.topic("topic-name").onPublish((message) => {
68+
// ...
69+
});
70+
```
71+
72+
**After (2nd Gen):**
73+
```typescript
74+
import {onMessagePublished} from "firebase-functions/v2/pubsub";
75+
76+
export consthellopubsub = onMessagePublished("topic-name", (event) => {
77+
// ...
78+
});
79+
```
80+
81+
## 4. Use Parameterized Configuration
82+
83+
Migrate from `functions.config()` to the new `params` module for environment configuration. This provides strong typing and validation.
84+
85+
**Before (`.runtimeconfig.json`):**
86+
```json
87+
{
88+
"someservice": {
89+
"key": "somesecret"
90+
}
91+
}
92+
```
93+
**And in code (1st Gen):**
94+
```typescript
95+
const SKEY = functions.config().someservice.key;
96+
```
97+
98+
**After (2nd Gen):**
99+
Define params in your code and set their values during deployment.
100+
101+
**In `index.ts`:**
102+
```typescript
103+
import {defineString} from "firebase-functions/params";
104+
105+
const SOMESERVICE_KEY = defineString("SOMESERVICE_KEY");
106+
```
107+
Use `SOMESERVICE_KEY.value()` to access the value. For secrets like API keys, use `defineSecret`.
108+
109+
**In `index.ts`:**
110+
```typescript
111+
import {defineSecret} from "firebase-functions/params";
112+
113+
const SOMESERVICE_KEY = defineSecret("SOMESERVICE_KEY");
114+
```
115+
You will be prompted to set the value on deployment, which is stored securely in Cloud Secret Manager.
116+
117+
## 5. Update Runtime Options
118+
119+
Runtime options are now set directly within the function definition.
120+
121+
**Before (1st Gen):**
122+
```typescript
123+
export const func = functions
124+
.runWith({
125+
// Keep 5 instances warm
126+
minInstances: 5,
127+
})
128+
.https.onRequest((request, response) => {
129+
// ...
130+
});
131+
```
132+
133+
**After (2nd Gen):**
134+
```typescript
135+
import {onRequest} from "firebase-functions/v2/https";
136+
137+
export const func = onRequest(
138+
{
139+
// Keep 5 instances warm
140+
minInstances: 5,
141+
},
142+
(request, response) => {
143+
// ...
144+
}
145+
);
146+
```
147+
148+
## 6. Traffic Migration
149+
150+
To migrate traffic safely:
151+
1. Rename your new 2nd gen function with a different name.
152+
2. Deploy it alongside the old 1st gen function.
153+
3. Gradually introduce traffic to the new function (e.g., via client-side changes or by calling it from the 1st gen function).
154+
4. Once you are confident, you can delete the 1st gen function.

‎.guides/usage.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
This guide covers Firebase Functions SDK v6.0.0+.
2+
3+
**Key Guidelines**
4+
* Always use v2 functions for new development.
5+
* Use v1 functions *only* for Analytics, basic Auth, and Test Lab triggers.
6+
* For SDK versions before 6.0.0, add `/v2` to import paths (e.g., `firebase-functions/v2/https`).
7+
8+
**Configuration: Use Secret Params for API Keys**
9+
For sensitive information like API keys (e.g., for LLMs, payment providers, etc.), **always** use `defineSecret`. This stores the value securely in Cloud Secret Manager.
10+
11+
```typescript
12+
import {onRequest} from 'firebase-functions/v2/https';
13+
import {logger} from 'firebase-functions/logger';
14+
import {defineString, defineSecret} from 'firebase-functions/params';
15+
16+
// Securely define an LLM API key
17+
const LLM_API_KEY = defineSecret('LLM_API_KEY');
18+
19+
// Example function that uses the secret
20+
export const callLlm = onRequest({ secrets: [LLM_API_KEY] }, (req, res) => {
21+
const apiKey = LLM_API_KEY.value();
22+
23+
// Use the apiKey to make a call to the LLM service
24+
logger.info('Calling LLM with API key.');
25+
26+
res.send('LLM API call initiated.');
27+
});
28+
```
29+
When you deploy a function with `secrets`, the CLI will prompt you to enter the secret's value.
30+
31+
**Initializing the Firebase Admin SDK**
32+
To interact with Firebase services like Firestore, Auth, or RTDB from within your functions, you need to initialize the Firebase Admin SDK.
33+
34+
1. **Install the SDK:**
35+
```bash
36+
npm i firebase-admin
37+
```
38+
39+
2. **Initialize in your code:**
40+
```typescript
41+
import * as admin from 'firebase-admin';
42+
43+
admin.initializeApp();
44+
```
45+
This should be done once at the top level of your `index.ts` file.
46+
47+
**Common Imports**
48+
```typescript
49+
// HTTPS, Firestore, RTDB, Scheduled, Storage, Pub/Sub, Auth, Logging, Config
50+
import {onRequest} from 'firebase-functions/https';
51+
import {onDocumentUpdated} from 'firebase-functions/firestore';
52+
import {onValueWritten} from 'firebase-functions/database';
53+
import {onSchedule} from 'firebase-functions/scheduler';
54+
import {onObjectFinalized} from 'firebase-functions/storage';
55+
import {onMessagePublished} from 'firebase-functions/pubsub';
56+
import {beforeUserSignedIn} from 'firebase-functions/identity';
57+
import {logger} from 'firebase-functions';
58+
import {defineString, defineSecret} from 'firebase-functions/params';
59+
```
60+
61+
**v1 Functions (Legacy Triggers)**
62+
Use the `firebase-functions/v1` import for Analytics and basic Auth triggers.
63+
```typescript
64+
import * as functionsV1 from 'firebase-functions/v1';
65+
66+
// v1 Analytics trigger
67+
export const onPurchase = functionsV1.analytics.event('purchase').onLog((event) => {
68+
logger.info('Purchase event', { value: event.params?.value });
69+
});
70+
71+
// v1 Auth trigger
72+
export const onUserCreate = functionsV1.auth.user().onCreate((user) => {
73+
logger.info('User created', { uid: user.uid });
74+
});
75+
```
76+
77+
**Development Commands**
78+
```bash
79+
# Install dependencies
80+
npm install
81+
82+
# Compile TypeScript
83+
npm run build
84+
85+
# Run emulators for local development
86+
firebase emulators:start --only functions
87+
88+
# Deploy functions
89+
firebase deploy --only functions
90+
```

0 commit comments

Comments
 (0)