Wdrażanie aplikacji full stack Next.js w Cloud Run z Firestore za pomocą pakietu Node.js Admin SDK

Informacje o tym ćwiczeniu (w Codelabs)

Ostatnia aktualizacja: kwi 11, 2025

Autorzy: Luke Schlangen

1. Omówienie

Cloud Run to w pełni zarządzana platforma, która umożliwia uruchamianie kodu bezpośrednio w infrastrukturze Google o wysokiej skalowalności. W tym Codelab pokażemy, jak połączyć aplikację Next.js w Cloud Run z bazą danych Firestore za pomocą pakietu SDK Admin Node.js.

W tym module nauczysz się, jak:

Utwórz bazę danych Firestore
Wdrażanie w Cloud Run aplikacji, która łączy się z bazą danych Firestore

2. Wymagania wstępne

Jeśli nie masz jeszcze konta Google, utwórz je.
- Używasz konta osobistego, a nie służbowego ani szkolnego. Konta służbowe i szkolne mogą mieć ograniczenia, które uniemożliwiają włączenie interfejsów API potrzebnych w tym laboratorium.

3. Konfigurowanie projektu

Zaloguj się w konsoli Google Cloud.
Włącz rozliczenia w Cloud Console.
- Ukończenie tego ćwiczenia powinno kosztować mniej niż 1 USD w zasobach Cloud.
- Aby uniknąć dalszych opłat, możesz usunąć zasoby, wykonując czynności opisane na końcu tego modułu.
- Nowi użytkownicy mogą skorzystać z bezpłatnego okresu próbnego, w którym mają do dyspozycji środki w wysokości 300 USD.
Utwórz nowy projekt lub użyj istniejącego.

4. Otwórz edytor Cloud Shell

Otwórz Edytor Cloud Shell.
Jeśli terminal nie pojawia się u dołu ekranu, otwórz go:
- Kliknij menu z 3 kreskami
- Kliknij Terminal.
- Kliknij Nowy terminal.
W terminalu skonfiguruj projekt za pomocą tego polecenia:
- Format:
```
gcloud config set project [PROJECT_ID]
```
- Przykład:
```
gcloud config set project lab-project-id-example
```
- Jeśli nie pamiętasz identyfikatora projektu:
  - Aby wyświetlić wszystkie identyfikatory projektów, użyj:
```
gcloud projects list | awk '/PROJECT_ID/{print $2}'
```
Jeśli pojawi się pytanie o autoryzację, kliknij Autoryzuj, aby kontynuować.
Powinien wyświetlić się ten komunikat:
```
Updated property [core/project].
```
Jeśli widzisz WARNING i pojawia się pytanie Do you want to continue (Y/N)?, prawdopodobnie nieprawidłowo wpisano identyfikator projektu. Naciśnij N, naciśnij Enter i spróbuj ponownie uruchomić polecenie gcloud config set project.

5. Włącz interfejsy API

Włącz w terminalu te interfejsy API:

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

Jeśli pojawi się pytanie o autoryzację, kliknij Autoryzuj, aby kontynuować. Kliknij, aby autoryzować Cloud Shell

Wykonanie tego polecenia może potrwać kilka minut, ale ostatecznie powinno wyświetlić komunikat podobny do tego:

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

6. Tworzenie bazy danych Firestore

Aby utworzyć bazę danych Firestore, uruchom polecenie gcloud firestore databases create
```
gcloud firestore databases create --location=nam5
```

7. Przygotowanie aplikacji

Przygotuj aplikację Next.js, która odpowiada na żądania HTTP.

Aby utworzyć nowy projekt Next.js o nazwie task-app, użyj polecenia:

npx --yes create-next-app@15.2.4 task-app \
  --ts \
  --eslint \
  --tailwind \
  --no-src-dir \
  --turbopack \
  --app \
  --no-import-alias

Zmień katalog na task-app:
```
cd task-app
```

Zainstaluj firebase-admin, aby korzystać z bazy danych Firestore.
```
npm install firebase-admin
```

Otwórz plik actions.ts w edytorze Cloud Shell:
```
cloudshell edit app/actions.ts
```
W górnej części ekranu powinien pojawić się pusty plik. Tutaj możesz edytować plik actions.ts.

Skopiuj ten kod i wklej go do otwartego pliku actions.ts:

'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;
}

Otwórz plik page.tsx w edytorze Cloud Shell:
```
cloudshell edit app/page.tsx
```
W górnej części ekranu powinien pojawić się istniejący plik. Tutaj możesz edytować plik page.tsx.
Usuń istniejące treści z pliku page.tsx.

Skopiuj ten kod i wklej go do otwartego pliku page.tsx:

'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>
  );
}

Aplikacja jest teraz gotowa do wdrożenia.

8. Wdrażanie aplikacji w Cloud Run

Aby wdrożyć aplikację do Cloud Run, uruchom to polecenie:

gcloud run deploy helloworld \
  --region=us-central1 \
  --source=.

Jeśli pojawi się taka prośba, naciśnij Y i Enter, aby potwierdzić, że chcesz kontynuować:
```
Do you want to continue (Y/n)? Y
```

Po kilku minutach aplikacja powinna wyświetlić adres URL, który należy otworzyć.

Otwórz adres URL, aby zobaczyć aplikację w akcji. Za każdym razem, gdy otworzysz adres URL lub odświeżysz stronę, zobaczysz aplikację do zadań.

9. Gratulacje

Z tego modułu nauczysz się:

Utwórz instancję Cloud SQL for PostgreSQL
Wdrażanie w Cloud Run aplikacji, która łączy się z bazą danych Cloud SQL

Czyszczenie danych

Cloud SQL nie ma bezpłatnego poziomu i będzie pobierać opłaty za dalsze korzystanie z usługi. Aby uniknąć dodatkowych opłat, możesz usunąć projekt Cloud.

Cloud Run nie nalicza opłat, gdy usługa nie jest używana, ale może zostać pobrana należność za przechowywanie obrazu kontenera w Artifact Registry. Usunięcie projektu Cloud powoduje zaprzestanie naliczania opłat za wszystkie zasoby używane w tym projekcie.

Jeśli chcesz, możesz usunąć projekt:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Możesz też usunąć niepotrzebne zasoby z dysku CloudShell. Możesz:

Usuń katalog projektu ćwiczeń z programowania:
```
rm -rf ~/task-app
```
Ostrzeżenie! Tej czynności nie można cofnąć. Jeśli chcesz usunąć wszystko z Cloud Shell, aby zwolnić miejsce, możesz usunąć cały katalog domowy. Upewnij się, że wszystko, co chcesz zachować, jest zapisane gdzie indziej.
```
sudo rm -rf $HOME
```

Ucz się dalej

Zgłoś pomyłkę