1. Before you begin
Firebase Extensions allow you to add pre-packaged functionality to your apps with minimal code – even AI-powered functionality. This codelab shows you how to integrate two Firebase Extensions in a web app so that you can leverage the Gemini API to generate image descriptions, summarizations, and even personalized recommendations based on provided context and end user input.
In this codelab, you'll learn how to build an AI-powered web app that provides compelling user experiences with Firebase Extensions.
Prerequisites
- Knowledge of Node.js, Next.js, and TypeScript.
What you'll learn
- How to use Firebase Extensions for the Gemini API to process language.
- How to use Cloud Functions for Firebase to compose an augmented context for your language model.
- How to use JavaScript to access output produced by Firebase Extensions.
What you'll need
- A browser of your choice, such as Google Chrome
- A development environment with a code editor and terminal
- A Google Account for the creation and management of your Firebase project
2. Review the web app, Firebase services, and extensions
In this section, you'll review the web app that you'll build with this codelab, as well learn about the Firebase services and Firebase Extensions that you'll use.
Web app
In this codelab, you'll build a web app called Friendly Conf.
The Friendly Conference staff decided to use AI to produce a delightful and personalized user experience for their attendees. The completed conference app provides attendees with a conversational AI chatbot that's powered by a multimodal generative AI model (also known as a large language model or LLM), and it can answer questions about general topics, tailored to the conference schedule and topics. The chatbot has historical context and knowledge about the current date/time and the Friendly Conf topics and schedule, so its responses can factor in all this context.
Firebase services
In this codelab, you'll use many Firebase services and features, and most of the starter code for them is provided for you. The following table contains the services that you'll use and the reasons for using them.
Service | Reason for use |
You use sign-in-with-Google functionality for the web app. | |
You store text data in Cloud Firestore, which is then processed by the Firebase Extensions. | |
You read and write from Cloud Storage to display image galleries within the web app. | |
You deploy Security Rules to help secure access to your Firebase services. | |
You configure and install AI-related Firebase Extensions and display the results within the web app. | |
You can optionally use the Local Emulator Suite to run your app locally, instead of connecting to many live Firebase services in the cloud. | |
Bonus: Firebase Hosting | You can optionally use Firebase Hosting to serve your web app (without a GitHub repo). |
Bonus: Firebase App Hosting | You can optionally use the new streamlined Firebase App Hosting to serve your dynamic Next.js web app (connected to a GitHub repo). |
Firebase Extensions
The Firebase Extensions that you'll use in this codelab include the following:
Extensions are useful because they react to events that happen in your Firebase project. Both of the extensions used in this codelab respond when you create new documents in preconfigured collections in Cloud Firestore.
3. Set up your development environment
Verify your Node.js version
- In your terminal, verify that you have Node.js version 20.0.0 or higher installed:
node -v
- If you don't have Node.js version 20.0.0 or higher, download the latest LTS version and install it.
Get the source code for the codelab
If you have a GitHub account:
- Create a new repository using our template from github.com/FirebaseExtended/codelab-gemini-api-extensions
- Clone the codelab's GitHub repository you just created:
git clone https://github.com/<your-github-handle>/codelab-gemini-api-extensions
If you don't have git installed or prefer to not create a new repo:
Download the GitHub repository as a zip file.
Review the folder structure
The root folder includes a README.md
file that offers a quick start to run the web app, using streamlined instructions. However, if you're a first-time learner, you should complete this codelab (instead of the quickstart) because the codelab contains the most comprehensive set of instructions.
If you're unsure of whether you correctly applied code as instructed throughout this codelab, you can find the solution code in the end
git branch.
Install the Firebase CLI
- Verify that you have the Firebase CLI installed and that it's version 13.6 or higher:
firebase --version
- If you have the Firebase CLI installed, but it's not version 13.6 or higher, update it:
npm update -g firebase-tools
- If you don't have the Firebase CLI installed, install it:
npm install -g firebase-tools
If you're unable to update or install the Firebase CLI because of permission errors, see the npm documentation or use another installation option.
Log into Firebase
- In your terminal, navigate to the
codelab-gemini-api-extensions
folder and log in to Firebase: If your terminal says that you're already logged in to Firebase, you can skip to the Set up your Firebase project section of this codelab.cd codelab-gemini-api-extensions firebase login
- In your terminal, depending on whether you want Firebase to collect data, enter
Y
orN
. (either option works for this codelab) - In your browser, select your Google Account and click Allow.
4. Set up your Firebase project
In this section, you'll set up a Firebase project and register a Firebase Web App in it. You'll also enable a few Firebase services used by the sample web app later in this codelab.
All of the steps in this section are performed in the Firebase console.
Create a Firebase project
- Sign into the Firebase console using a Google Account.
- Click Create a project, and then enter a project name (for example,
AI Extensions Codelab
).
Remember the auto-assigned project ID for your Firebase project (or click the Edit icon to set your preferred project ID). You'll need this ID later to identify your Firebase project in the Firebase CLI. If you forget your ID, you can always find it later in the Project Settings. - Click Continue.
- If prompted, review and accept the Firebase terms, and then click Continue.
- For this codelab, you do not need Google Analytics, so toggle off the Google Analytics option.
- Click Create project, wait for your project to provision, and then click Continue.
Add a web app to your Firebase project
- Navigate to the Project Overview screen in your Firebase project, and then click
Web.
- In the App nickname text box, enter a memorable app nickname, such as
My AI Extensions
- Click Register app > Next > Next > Continue to console.
You can skip all the steps related to "hosting" in the Web App flow because you'll be optionally setting up a hosting service later in this codelab.
Great! You have now registered a web app in your new Firebase project.
Upgrade your Firebase billing plan
To use Firebase Extensions and their underlying cloud services, you need to upgrade your Firebase project to enable billing.
Also note that with billing enabled on your Firebase project, you'll be charged for the calls that the extension makes to the Gemini API (no matter which provider you choose, Google AI or Vertex AI). Learn more about pricing for Google AI and for Vertex AI.
To upgrade your project's billing plan, follow these steps:
- Navigate to Firebase Billing Plans within your Firebase project.
- In the Firebase billing plans dialog, select the Blaze plan and purchase it.
Enable Firebase Authentication
- Navigate to Authentication using the left-navigation pane.
- Click Get started.
- In the Additional providers column, click Google > Enable.
- In the Public-facing name for project text box, enter a useful name, such as
My AI Extensions Codelab
. - In the Support email for project menu, select your email address.
- Click Save.
Enable Cloud Firestore
- Navigate to Firestore using the left-navigation pane.
- Click Create database > Start in test mode > Next. Later in this codelab, you'll deploy more robust Firebase Security Rules.
- Select your preferred Cloud Firestore location (or just leave it as the default).
- Click Enable.
Enable Cloud Storage for Firebase
- Navigate to Storage using the left-navigation pane.
- Click Get started > Start in test mode > Next. Later in this codelab, you'll deploy more robust Firebase Security Rules.
- Since you set up Firestore in your project first, the location of your default Cloud Storage bucket is already set.
- Click Done.
In the next section of this codelab, you'll install and configure the two Firebase Extensions that you'll use in the web app throughout this codelab.
5. Set up the "Build Chatbot with the Gemini API" extension
Install the "Build Chatbot with the Gemini API" extension
- Navigate to the "Build Chatbot with the Gemini API" extension".
- Click Install in the Firebase console.
- Select your Firebase project, and then click Next.
- In the Review APIs enabled and resources created section, click Enable next to any services that are suggested to you, and then click Next.
- For any permissions that are suggested to you, select Grant, and then click Next.
- Configure the extension:
- In the Gemini API Provider menu, select whether you want to use the Gemini API from Google AI or Vertex AI. For developers using Firebase, we recommend using
Vertex AI
. - In the Firestore Collection Path text box, enter:
users/{uid}/messages
.
In future steps of this codelab, adding documents to this collection will trigger the extension to call the Gemini API. - In the Cloud Functions location menu, select your preferred location (like
Iowa (us-central1)
or the location that you previously specified for your Firestore database). - Leave all other values as their default.
- In the Gemini API Provider menu, select whether you want to use the Gemini API from Google AI or Vertex AI. For developers using Firebase, we recommend using
- Click Install extension and wait for the extension to install.
Try out the "Build Chatbot with the Gemini API" extension
While the goal of this codelab is to interact with the "Build Chatbot with the Gemini API" extension through a web app, it's helpful to learn how the extension works by trying it out in the Firebase console first.
The extension is triggered whenever a Firestore document is created under the collection users/{uid}/discussion/{discussionId}/messages
, which you can do in the Firebase console.
- In the Firebase console, navigate to Firestore, and then click
Start collection within the first column.
- In the Collection ID text box, enter
users
, and then click Next. - In the Document ID text box, click Auto-ID, and then click Save.
- In the
users
collection, clickStart collection.
- In the Collection ID text box, enter
messages
, and then click Next.- In the Document ID text box, click Auto-ID.
- In the Field text box, enter
prompt
- In the Value text box, enter
Tell me 5 random fruits
- Click Save and wait a few seconds.
When you added this document, it triggered the extension to call the Gemini API. The document that you just added to the messages
collection now includes not only your prompt
but also now the model's response
to your query.
Trigger the extension again by adding another document to the messages
collection:
- In the
messages
collection, clickAdd document.
- In the Document ID text box, click Auto-ID.
- In the Field text box, enter
prompt
- In the Value text box, enter
And now, vegetables
- Click Save and wait a few seconds. The document you just added to the
messages
collection now includes aresponse
to your query.
When generating this response, the underlying Gemini model used the historical knowledge from your previous query.
6. Set up the web app
To run the web app, you'll need to run commands in your terminal and add code within your code editor.
Set up the Firebase CLI to run against your Firebase project
In your terminal, tell the CLI to use your Firebase project by running the following command:
firebase use YOUR_PROJECT_ID
Deploy Security Rules for Firestore and Cloud Storage
This codelab's codebase already has a set of Firestore Security Rules and Cloud Storage Security Rules written for you. Once you deploy these Security Rules, your Firebase services in your Firebase project are better protected from misuse.
- To deploy Security Rules, run this command in your terminal:
firebase deploy --only firestore:rules,storage
- If asked whether to grant Cloud Storage the IAM Role to use cross-service rules, enter
Y
orN
. (either option works for this codelab)
Connect your web app to your Firebase project
Your web app's codebase needs to know which Firebase project it should use for its database, storage, etc. You do this by adding your Firebase configuration to your app's codebase.
- Obtain your Firebase configuration:
- In the Firebase console, navigate to Project settings within your Firebase project.
- Scroll down to the Your apps section, and select your registered web app.
- In the SDK setup and configuration pane, copy the full
initializeApp
code including thefirebaseConfig
const.
- Add your Firebase configuration to your web app's codebase:
- In your code editor, open the
src/app/lib/firebase/firebase.config.js
file. - Select all in the file, and replace with the code that you copied.
- Save the file.
- In your code editor, open the
Preview the web app in your browser
- In your terminal, install dependencies and then run the web app:
npm install npm run dev
- In your browser, navigate to the locally hosted Hosting URL to view the web app. For example, in most cases, the URL is http://localhost:3000/ or something similar.
Use the web app's chatbot
- In your browser, return to the tab with the locally running Friendly Conf web app.
- Click Sign in with Google, and if necessary, select your Google Account.
- After you have signed in, you'll see an empty chat window.
- Type in a greeting (like
hi
), and then click Send. - Wait a few seconds for the chatbot to respond.
The chatbot in the app responds with a generic response.
Specialize the chatbot for the app
You need the underlying Gemini model used by your web app's chatbot to know conference-specific details when the model generates responses for attendees using the app. There are lots of ways to control and steer these responses, and in this codelab's sub-section, we're showing you a very basic way by providing "context" in the initial prompt (rather than only the input from the user of the web app).
- In the web app in your browser, clear the conversation by clicking the red "x" button (next to the message in the chat history).
- In your code editor, open the
src/app/page.tsx
file. - Scroll down and replace the code on or near line 77 that says
prompt: userMsg
with the following:prompt: preparePrompt(userMsg, messages),
- Save the file.
- Go back to the web app running in your browser.
- Again, type in a greeting (like
hi
), and then click Send. - Wait a few seconds for the chatbot to respond.
The chatbot responds with knowledge guided by the context provided in src/app/lib/context.md
. Even though you didn't type in a specific request, the underlying Gemini model generates a personalized recommendation based on this context as well as the current date/time. Now you can specify follow-up questions and dive deeper.
This expanded context is important for the chatbot, but you shouldn't show it to the user of the web app. Here's how to hide it:
- In your code editor, open the
src/app/page.tsx
file. - Scroll down and replace the code on or near line 56 that says
...doc.data(),
with the following:...prepareMessage(doc.data()),
- Save the file.
- Go back to the web app running in your browser.
- Reload the page.
You can also try out the ability to converse with the chatbot with historical context:
- In the Type a message text box, ask a question like:
Any other interesting talks about AI?
The chatbot will return a response. - In the Type a message text box, ask a follow-up question that's related to the previous question:
Give me a few more details about the last one.
The chatbot responds with historical knowledge. Since the chat history is now part of the context, the chatbot understands follow-up questions.
Bonus: Run the web app using the Firebase Local Emulator Suite
The Firebase Local Emulator Suite allows you to test locally most of the features of the web app.
- In your terminal, make sure that you're at the root of the web app.
- Run the following command to install and then run the Firebase Local Emulator Suite:
firebase init emulators firebase emulators:start
7. Set up the "Multimodal Tasks with the Gemini API" extension
The "Multimodal Tasks with the Gemini API" extension calls the Gemini API with multimodal prompts that contain a text prompt as well as a supported file URL or Cloud Storage URL (note that even the Google AI Gemini API uses a Cloud Storage URL as its underlying file URL infrastructure). The extension also supports handlebars variables to substitute values from the Cloud Firestore document for customizing the text prompt.
In your app, whenever you upload an image to a Cloud Storage bucket, you can generate a URL and add that URL to a new Cloud Firestore document – thus triggering the extension to create a multimodal prompt and call the Gemini API. In this codelab's source code, we've already provided the code for uploading an image and writing the URL to a Firestore document.
Install the "Multimodal Tasks with the Gemini API" extension
- Navigate to the "Multimodal Tasks with the Gemini API" extension".
- Click Install in the Firebase console.
- Select your Firebase project.
- Click Next > Next > Next, until you reach the Configure extension section.
- In the Gemini API Provider menu, select whether you want to use the Gemini API from Google AI or Vertex AI. For developers using Firebase, we recommend using
Vertex AI
. - In the Firestore Collection Path text box, enter:
gallery
- In the Prompt text box, enter:
Please describe the provided image; if there is no image, say "no image"
- In the Image field text box, enter:
image
- In the Cloud Functions location menu, select your preferred location (like
Iowa (us-central1)
or the location that you previously specified for your Firestore database). - Leave all other values as their default.
- In the Gemini API Provider menu, select whether you want to use the Gemini API from Google AI or Vertex AI. For developers using Firebase, we recommend using
- Click Install extension and wait for the extension to install.
Try out the "Multimodal Tasks with the Gemini API" extension
While the goal of this codelab is to interact with the "Multimodal Tasks with the Gemini API" extension through a web app, it's helpful to learn how the extension works by trying it out in the Firebase console first.
The extension is triggered whenever a Firestore document is created under the collection users/{uid}/gallery
, which you can do in the Firebase console. The extension then takes the Cloud Storage image URL in the Cloud Firestore document and passes it as part of the multimodal prompt in a call to the Gemini API.
First, upload an image to a Cloud Storage bucket:
- Navigate to Storage within your Firebase project.
- Click
Create folder.
- In the Folder name text box, enter
gallery
- Click Add folder.
- In the
gallery
folder, click Upload file. - Select a JPEG image file to upload.
Next, add the Cloud Storage URL for the image to a Firestore document (which is the trigger for the extension):
- Navigate to Firestore within your Firebase project
- Click
Start collection within the first column.
- In the Collection ID text box, enter:
gallery
, and then click Next. - Add a document to the collection:
- In the Document ID text box, click Auto-ID.
- In the Field text box, enter:
image
. In the Value box enter the Storage location uri of the image you just uploaded.
- Click Add Field.
- In the Field text box, enter:
published
. In the Type box select boolean. In the Value box selecttrue
. - Click Save and wait a few seconds.
The gallery
collection now includes a document that contains a response to your query.
Use the web app's image gallery
- In your browser, return to the tab with the locally running Friendly Conf web app.
- Click on the Gallery navigation tab.
- You will see a gallery of uploaded images and AI generated descriptions. It should have the image you uploaded earlier to the
gallery
folder in your Storage bucket. - Click the button to "Upload" and select another JPEG image.
- Wait a few seconds for the image to show in the gallery. A few moments later, the AI generated description for the newly uploaded image will be displayed, as well.
If you want to understand the code for how this was implemented, see src/app/gallery/page.tsx
in the web app's codebase.
8. Bonus: Deploy your application
Firebase offers several ways in which you can deploy a web application. For this codelab, choose one of the following options:
- Option 1: Firebase Hosting - Use this option if you decide to not create your own GitHub repo (and only have your source code stored locally on your machine).
- Option 2: Firebase App Hosting - Use this option if you want automatic deployment anytime you push changes to your own GitHub repo. This new Firebase service is built specifically to tailor to the needs of dynamic Next.js and Angular applications.
Option 1: Deploy using Firebase Hosting
Use this option if you decide to not create your own GitHub repo (and only have your source code stored locally on your machine).
- In your terminal, initialize Firebase Hosting by running these commands:
firebase experiments:enable webframeworks firebase init hosting
- For the prompt:
Detected an existing Next.js codebase in your current directory, should we use this?
, pressY
. - For the prompt:
In which region would you like to host server-side content, if applicable?
, select either the default location or the location that you used earlier in this codelab. Then pressEnter
(orreturn
on macOS). - For the prompt:
Set up automatic builds and deploys with GitHub?
, pressN
. - Deploy your web app to Hosting by running this command:
firebase deploy --only hosting
All done! If you update your app and want to deploy that new version, just rerun firebase deploy --only hosting
and Firebase Hosting will build and re-deploy your app.
Option 2: Deploy using Firebase App Hosting
Use this option if you want automatic deployment anytime you push changes to your own GitHub repo.
- Commit your changes to GitHub.
- In the Firebase console, navigate to App Hosting within your Firebase project.
- Click Get started > Connect to GitHub.
- Select your GitHub account and Repository. Click Next.
- In Deployment setting > Root directory, enter the name of the folder with your source code (if your
package.json
is not in the root directory of your repository). - For the Live branch, select the main branch of your GitHub repo. Click Next.
- Enter an ID for your backend (for example,
chatbot
). - Click Finish and Deploy.
It will take a few minutes for your new deployment to be ready. You can check the deployment status in the App Hosting section of the Firebase console.
From this point forward, each time that you push a change to your GitHub repo, Firebase App Hosting will automatically build and deploy your app.
9. Conclusion
Congratulations! You achieved a lot in this codelab!
Installing and configuring extensions
You used the Firebase console to configure and install various Firebase Extensions that use generative AI. Using Firebase Extensions is convenient because you don't need to learn about and write lots of boilerplate code to handle authenticating with Google Cloud services or the backend Cloud Functions logic to listen to and interact with Firestore and Google Cloud services and APIs.
Trying out extensions using the Firebase console
Instead of jumping straight into code, you took time to understand how these genAI extensions work, based on an input that you provided through Firestore or Cloud Storage. This can be especially useful while debugging the output of an extension.
Building an AI-powered web app
You built an AI-powered web app that uses Firebase Extensions to access just a few capabilities of the Gemini model.
In the web app, you use the "Chatbot with Gemini API" extension to provide the user with an interactive chat interface, that includes app-specific and historical context in conversations - where each message is stored in a Firestore document that is scoped to a particular user.
The web app also used the "Multimodal Tasks with the Gemini API" extension to auto-generate image descriptions for uploaded images.
Next steps
- Experiment with prompts and take advantage of the large context window in Google AI Studio or Vertex AI Studio.
- Learn about AI retrieval augmented generation (RAG) search.
- Try a self-paced codelab showing how to add a chatbot to an existing Firebase app using Firebase Genkit (which is a new AI framework service).
- Learn about similarity search capabilities in Firestore and Cloud SQL for PostgreSQL.
- Teach your chatbot to call into your existing app with function calling.