Deploy a full stack Next.js application to Cloud Run with Firestore using the Node.js Admin SDK

1. Overview

Cloud Run is a fully managed platform that enables you to run your code directly on top of Google's scalable infrastructure. This Codelab will demonstrate how to connect a Next.js application on Cloud Run to a Firestore database using the Node.js Admin SDK.

In this lab, you will learn how to:

  • Create a Firestore database
  • Deploy an application to Cloud Run that connects to your Firestore database

2. Prerequisites

  1. If you do not already have a Google account, you must create a Google account.
    • Use a personal account instead of a work or school account. Work and school accounts may have restrictions that prevent you from enabling the APIs needed for this lab.

3. Project setup

  1. Sign-in to the Google Cloud Console.
  2. Enable billing in the Cloud Console.
    • Completing this lab should cost less than $1 USD in Cloud resources.
    • You can follow the steps at the end of this lab to delete resources to avoid further charges.
    • New users are eligible for the $300 USD Free Trial.
  3. Create a new project or choose to reuse an existing project.

4. Open Cloud Shell Editor

  1. Navigate to Cloud Shell Editor
  2. If the terminal doesn't appear on the bottom of the screen, open it:
    • Click the hamburger menu Hamburger menu icon
    • Click Terminal
    • Click New TerminalOpen new terminal in Cloud Shell Editor
  3. In the terminal, set your project with this command:
    • Format:
      gcloud config set project [PROJECT_ID]
    • Example:
      gcloud config set project lab-project-id-example
    • If you can't remember your project id:
      • You can list all your project ids with:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      Set project id in Cloud Shell Editor terminal
  4. If prompted to authorize, click Authorize to continue. Click to authorize Cloud Shell
  5. You should see this message:
    Updated property [core/project].
    If you see a WARNING and are asked Do you want to continue (Y/N)?, then you have likely entered the project ID incorrectly. Press N, press Enter, and try to run the gcloud config set project command again.

5. Enable APIs

In the terminal, enable the APIs:

gcloud services enable \
  firestore.googleapis.com \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com

If prompted to authorize, click Authorize to continue. Click to authorize Cloud Shell

This command may take a few minutes to complete, but it should eventually produce a successful message similar to this one:

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

6. Create Firestore Database

  1. Run the gcloud firestore databases create command to create a firestore database 
    gcloud firestore databases create --location=nam5

7. Prepare Application

Prepare a Next.js application that responds to HTTP requests.

  1. To create a new Next.js project named task-app, use the command:
    npx --yes create-next-app@15.2.4 task-app \
  --ts \
  --eslint \
  --tailwind \
  --no-src-dir \
  --turbopack \
  --app \
  --no-import-alias
  2. Change directory into task-app:
    cd task-app
  1. Install firebase-admin to interact with the Firestore database.
    npm install firebase-admin
  1. Open the actions.ts file in Cloud Shell Editor:
    cloudshell edit app/actions.ts
    An empty file should now appear in the top part of the screen. This is where you can edit this actions.ts file. Show that code goes in the top section of the screen
  2. Copy the following code and paste it into the opened actions.ts file:
    'use server'
import { initializeApp, applicationDefault, getApps } from 'firebase-admin/app';
import { getFirestore } from 'firebase-admin/firestore';
const credential = applicationDefault();

// Only initialize app if it does not already exist
if (getApps().length === 0) {
  initializeApp({ credential });
}

const db = getFirestore();
const tasksRef = db.collection('tasks');

type Task = {
  id: string;
  title: string;
  status: 'IN_PROGRESS' | 'COMPLETE';
  createdAt: number;
};

// CREATE
export async function addNewTaskToDatabase(newTask: string) {
  await tasksRef.doc().create({
    title: newTask,
    status: 'IN_PROGRESS',
    createdAt: Date.now(),
  });
  return;
}

// READ
export async function getTasksFromDatabase() {
  const snapshot = await tasksRef.orderBy('createdAt', 'desc').limit(100).get();
  const tasks = await snapshot.docs.map(doc => ({
    id: doc.id,
    title: doc.data().title,
    status: doc.data().status,
    createdAt: doc.data().createdAt,
  }));
  return tasks;
}

// UPDATE
export async function updateTaskInDatabase(task: Task) {
  await tasksRef.doc(task.id).set(task);
  return;
}

// DELETE
export async function deleteTaskFromDatabase(taskId: string) {
  await tasksRef.doc(taskId).delete();
  return;
}
  1. Open the page.tsx file in Cloud Shell Editor:
    cloudshell edit app/page.tsx
    An existing file should now appear in the top part of the screen. This is where you can edit this page.tsx file. Show that code goes in the top section of the screen
  2. Delete the existing contents of the page.tsx file.
  3. Copy the following code and paste it into the opened page.tsx file:
    'use client'
import React, { useEffect, useState } from "react";
import { addNewTaskToDatabase, getTasksFromDatabase, deleteTaskFromDatabase, updateTaskInDatabase } from "./actions";

type Task = {
  id: string;
  title: string;
  status: 'IN_PROGRESS' | 'COMPLETE';
  createdAt: number;
};

export default function Home() {
  const [newTaskTitle, setNewTaskTitle] = useState('');
  const [tasks, setTasks] = useState<Task[]>([]);

  async function getTasks() {
    const updatedListOfTasks = await getTasksFromDatabase();
    setTasks(updatedListOfTasks);
  }

  useEffect(() => {
    getTasks();
  }, []);

  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    await addNewTaskToDatabase(newTaskTitle);
    await getTasks();
    setNewTaskTitle('');
  };

  async function updateTask(task: Task, newTaskValues: Partial<Task>) {
    await updateTaskInDatabase({ ...task, ...newTaskValues });
    await getTasks();
  }

  async function deleteTask(taskId: string) {
    await deleteTaskFromDatabase(taskId);
    await getTasks();
  }

  return (
    <main className="p-4">
      <h2 className="text-2xl font-bold mb-4">To Do List</h2>
      <div className="flex mb-4">
        <form onSubmit={handleSubmit} className="flex mb-8">
          <input
            type="text"
            placeholder="New Task Title"
            value={newTaskTitle}
            onChange={(e) => setNewTaskTitle(e.target.value)}
            className="flex-grow border border-gray-400 rounded px-3 py-2 mr-2 bg-inherit"
          />
          <button
            type="submit"
            className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded text-nowrap"
          >
            Add New Task
          </button>
        </form>
      </div>
      <table className="w-full">
        <tbody>
          {tasks.map(function (task) {
            const isComplete = task.status === 'COMPLETE';
            return (
              <tr key={task.id} className="border-b border-gray-200">
                <td className="py-2 px-4">
                  <input
                    type="checkbox"
                    checked={isComplete}
                    onChange={() => updateTask(task, { status: isComplete ? 'IN_PROGRESS' : 'COMPLETE' })}
                    className="transition-transform duration-300 ease-in-out transform scale-100 checked:scale-125 checked:bg-green-500"
                  />
                </td>
                <td className="py-2 px-4">
                  <span
                    className={`transition-all duration-300 ease-in-out ${isComplete ? 'line-through text-gray-400 opacity-50' : 'opacity-100'}`}
                  >
                    {task.title}
                  </span>
                </td>
                <td className="py-2 px-4">
                  <button
                    onClick={() => deleteTask(task.id)}
                    className="bg-red-500 hover:bg-red-700 text-white font-bold py-2 px-4 rounded float-right"
                  >
                    Delete
                  </button>
                </td>
              </tr>
            );
          })}
        </tbody>
      </table>
    </main>
  );
}

The application is now ready to be deployed.

8. Deploy the application to Cloud Run

  1. Run the command below to deploy your application to Cloud Run:
    gcloud run deploy helloworld \
  --region=us-central1 \
  --source=.
  2. If prompted, press Y and Enter to confirm that you would like to continue:
    Do you want to continue (Y/n)? Y

After a few minutes, the application should provide a URL for you to visit.

Navigate to the URL to see your application in action. Every time you visit the URL or refresh the page, you will see the task app.

9. Congratulations

In this lab, you have learned how to do the following:

  • Create a Cloud SQL for PostgreSQL instance
  • Deploy an application to Cloud Run that connects to your Cloud SQL database

Clean up

Cloud SQL does not have a free tier and will charge you if you continue to use it. You can delete your Cloud project to avoid incurring additional charges.

While Cloud Run does not charge when the service is not in use, you might still be charged for storing the container image in Artifact Registry. Deleting your Cloud project stops billing for all the resources used within that project.

If you would like, delete the project:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

You may also wish to delete unnecessary resources from your cloudshell disk. You can:

  1. Delete the codelab project directory: 
    rm -rf ~/task-app
  2. Warning! This next action is can't be undone! If you would like to delete everything on your Cloud Shell to free up space, you can delete your whole home directory. Be careful that everything you want to keep is saved somewhere else. 
    sudo rm -rf $HOME