Add dotguides #1736

jhuleatt · 2025-09-26T14:15:20Z

Description

Adds guides for LLM-assisted development

gemini-code-assist · 2025-09-26T14:15:40Z

Summary of Changes

Hello @jhuleatt, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new set of comprehensive guides aimed at streamlining LLM-assisted development with Firebase Functions. These guides cover the entire lifecycle, from initial project setup and best practices for using the latest SDK features, to a detailed migration path for upgrading existing 1st generation functions to the more modern and efficient 2nd generation. The goal is to provide clear, actionable documentation to enhance developer productivity and ensure secure, scalable function deployments.

Highlights

New Guides for LLM-assisted Development: This PR introduces a new set of .guides specifically designed to assist with LLM-assisted development for Firebase Functions, covering setup, migration, and best practices.
Firebase Functions Setup Guide: A detailed step-by-step guide for initializing and setting up new Firebase Functions projects, focusing on v2 functions, TypeScript, structured logging, and parameterized configuration.
Firebase Functions Upgrade Guide: A comprehensive guide outlining the process of migrating existing Firebase Functions from 1st to 2nd generation, covering dependency updates, import changes, trigger definition updates, parameterized configuration, and runtime options.
Firebase Functions Usage Best Practices: A guide detailing best practices for using Firebase Functions SDK v6.0.0+, including secure secret management with defineSecret, Firebase Admin SDK initialization, and guidelines for using v1 functions for legacy triggers.
Guide Configuration: Adds a config.json file to define metadata and server configurations for the new guides, including mcpServers settings.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request adds guides for LLM-assisted development. The guides are well-structured and provide useful information for setting up, upgrading, and using Firebase Functions. I've found a few inconsistencies and typos in the code examples within the markdown files. My suggestions aim to correct these issues and improve the clarity and accuracy of the documentation.

.guides/examples/index.md

.guides/setup.md

.guides/upgrade.md

.guides/usage.md

.guides/examples/index.md

.guides/config.json

.guides/setup.md

mbleigh · 2025-09-26T17:02:08Z

.guides/upgrade.md

I think this can be really powerful, but we need to be careful. Maybe the goal of /upgrade should be to upgrade a single function at a time and the guide should be written in that way - like step 1 find v1 functions step 2 ask user which function to upgrade and then it has the guidance to do that.

Yeah that does sound safer. I've changed step 1 to find and prompt for a single function to migrate.

.guides/setup.md

.guides/usage.md

jhuleatt · 2025-10-03T15:02:27Z

.guides/upgrade.md

+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.


@taeold this seems like a cool opportunity for an mcp tool

MCP tools for something very niche like "find all v1 functions" are a bit of a tough sell for me, but what you can do is pre-specify shell commands that will get the info you want. For example a find or grep or sed command that helps it find all the files it needs to look at.

.guides/setup.md

.guides/usage.md

taeold · 2025-10-03T16:38:26Z

.guides/upgrade.md

+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.


Co-authored-by: Daniel Lee <[email protected]>

…ons into dotguides-pilot

egilmorez

Here's some thoughts Jeff, sorry it's closing in on 4pm on a Friday :)

egilmorez · 2025-10-03T19:15:10Z

.guides/config.json

@@ -0,0 +1,9 @@
+{
+  "description": "Use this library to build serverless functions for event triggers and HTTP using Firebase and Cloud Run Functions",


Are we saying "Firebase and Cloud Run Functions" very deliberately, for a good reason?

If not, I'd avoid mention of a separate product, and just go with "using Cloud Functions for Firebase."

egilmorez · 2025-10-03T19:16:26Z

.guides/setup.md

@@ -0,0 +1,69 @@
+# Cloud Functions for Firebase setup guide
+
+This guide provides a step-by-step process for setting up a new Firebase Functions project, tailored for a coding agent.


We should watch out for this non-official naming . . . suggest just "Cloud Functions."

Also suggest "coding agents."

egilmorez · 2025-10-03T19:18:55Z

.guides/setup.md

+
+**Key points for the agent:**
+
+- Always import from `firebase-functions/*` for new functions.


Do we want to call out the Auth and Analytics exceptions? "Always" is a strong word to a robot.

I'll remove this bullet point, I think we have enough examples in here that it isn't needed.

plus, everything is under "firebase-functions/*" so it isn't really saying anything

egilmorez · 2025-10-03T19:20:40Z

.guides/setup.md

+
+Use the Firebase Emulators to test your function locally before deploying.
+
+Tell the user to run the following command in a separate terminal window to start the emulators:


Would "developer" be a better term than user?

Just thinking of how literal-minded an agent might be.

I've updated to "human" #1736 (comment)

.guides/upgrade.md

egilmorez · 2025-10-03T19:30:27Z

.guides/upgrade.md

+> 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.  Add back the original `minInstances` and `maxInstances` settings to the 2nd gen function.
+> 6.  Once you are confident, you can delete the 1st gen function.


By the same token, I wonder how an agent will interpret its level of confidence . . . we may need to be more specific/ less emotional :).

egilmorez · 2025-10-03T19:32:52Z

.guides/usage.md

+- Always use 2nd-gen functions for new development.
+- Use 1st-gen functions _only_ for Analytics and basic Auth triggers.
+- 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.


Do we need to be clear that Auth and analytics are going to be exceptions to this rule RE top-level imports?

egilmorez · 2025-10-03T19:34:21Z

.guides/usage.md

+});
+```
+
+When you deploy a function with `secrets`, the CLI will prompt you to enter the secret's value. Alternatively, you can instruct the user to set the secret using the Firebase CLI command:


Deployment question again -- is the agent doing the deploying? If so, "you" is fine (agents are the New You!! :)

simplified this

egilmorez · 2025-10-03T19:37:51Z

README.md

- Read the full API reference: https://firebase.google.com/docs/reference/functions/
- Browse some examples: https://github.com/firebase/functions-samples
+- [Start with the quickstart](https://firebase.google.com/docs/functions/write-firebase-functions)
+- [Go through the guide](https://firebase.google.com/docs/functions/)


Should we point them to functions/get-started?

If our aim is more general, let's pluralize "guides"

egilmorez · 2025-10-03T19:39:15Z

README.md

- Browse some examples: https://github.com/firebase/functions-samples
+- [Start with the quickstart](https://firebase.google.com/docs/functions/write-firebase-functions)
+- [Go through the guide](https://firebase.google.com/docs/functions/)
+- [Read the full API reference](https://firebase.google.com/docs/reference/functions/)


This reference link goes to a top-level "nav" page that includes 1st gen. Do we want instead to go directly to https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions?"

egilmorez

Thanks Jeff!!

gemini cli-assisted first-pass

94fdcef

jhuleatt requested review from egilmorez and taeold September 26, 2025 14:15

github-project-automation bot added this to [Cloud] Extensions + Functions Sep 26, 2025

gemini-code-assist bot reviewed Sep 26, 2025

View reviewed changes

mbleigh reviewed Sep 26, 2025

View reviewed changes

taeold reviewed Sep 26, 2025

View reviewed changes

.guides/setup.md Outdated Show resolved Hide resolved

.guides/setup.md Outdated Show resolved Hide resolved

.guides/usage.md Outdated Show resolved Hide resolved

jhuleatt added 2 commits October 3, 2025 10:46

address review comments

90899a8

upgrade a single function at a time

6757a45

jhuleatt requested review from taeold and mbleigh October 3, 2025 14:57

run prettier

07d3019

jhuleatt commented Oct 3, 2025

View reviewed changes

taeold approved these changes Oct 3, 2025

View reviewed changes

github-project-automation bot moved this to Approved [PR] in [Cloud] Extensions + Functions Oct 3, 2025

jhuleatt and others added 5 commits October 3, 2025 13:13

add another way to set secrets

b12dd46

Co-authored-by: Daniel Lee <[email protected]>

review round 2

89d5c50

Merge branch 'dotguides-pilot' of github.com:firebase/firebase-functi…

f8fb34e

…ons into dotguides-pilot

add changelog

f46a92c

prettier

d4ee0c9

egilmorez reviewed Oct 3, 2025

View reviewed changes

jhuleatt added 3 commits October 3, 2025 16:04

Address review feedback

1bbf723

clarify when to delete 1st gen after upgrade

079ad3f

more review feedback

0ac2a60

jhuleatt requested a review from egilmorez October 3, 2025 20:15

egilmorez approved these changes Oct 3, 2025

View reviewed changes

prettier

ac93f7d

jhuleatt enabled auto-merge October 3, 2025 20:28

Merge branch 'master' into dotguides-pilot

3eaa99d

jhuleatt added this pull request to the merge queue Oct 7, 2025

Merged via the queue into master with commit 3901fa6 Oct 7, 2025
18 checks passed

github-project-automation bot moved this from Approved [PR] to Done in [Cloud] Extensions + Functions Oct 7, 2025

		@@ -0,0 +1,9 @@
		{
		"description": "Use this library to build serverless functions for event triggers and HTTP using Firebase and Cloud Run Functions",

		@@ -0,0 +1,69 @@
		# Cloud Functions for Firebase setup guide

		This guide provides a step-by-step process for setting up a new Firebase Functions project, tailored for a coding agent.


		Key points for the agent:

		- Always import from `firebase-functions/*` for new functions.


		Use the Firebase Emulators to test your function locally before deploying.

		Tell the user to run the following command in a separate terminal window to start the emulators:

Add dotguides #1736

Add dotguides #1736

Conversation

jhuleatt commented Sep 26, 2025

Description

Uh oh!

gemini-code-assist bot commented Sep 26, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

egilmorez left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment