Step 1: Set Up Firestore in Native Mode

1. Go to the Google Cloud Console.

2. Select your project.

3. In the left nav, go to Firestore → Create Database.

4. Choose Native mode, select a location (cannot be changed later), and create it.

Step 2: Create Your Node.js GAE App

File structure example:

my-app/
├── package.json
├── app.js
└── app.yaml

             

Step 3: Add Firestore SDK

In your project folder, run:

npm install firebase-admin  

Step 4: Initialize Firestore in app.js & use it

>>>NOTE: credentials and permission is setup in console --see at the bottom of this page

const express = require('express');
const admin = require('firebase-admin');

const app = express();

// Initialize the Firebase Admin SDK (uses Application Default Credentials on GAE)
admin.initializeApp();

// Get a Firestore reference
const db = admin.firestore();  //note no credintials setup or permissions that is done through console
app.get('/', async (req, res) => {
  try {
    // Example: Add a document
    const docRef = db.collection('messages').doc();  //the name of the collection is messages
    await docRef.set({
      text: 'Hello from GAE and Firestore Native Mode!',
      timestamp: new Date()
    });

    // Example: Read documents
    const snapshot = await db.collection('messages').orderBy('timestamp', 'desc').limit(5).get();
    const messages = snapshot.docs.map(doc => doc.data());

    res.send(messages);
  } catch (error) {
    console.error(error);
    res.status(500).send('Error connecting to Firestore');
  }
});

const PORT = process.env.PORT || 8080;
app.listen(PORT, () => {
  console.log(`App listening on port ${PORT}`);
});

You're Using Firestore, Not Firebase — So Why Use firebase-admin?

Even though you're not using the broader Firebase app platform (like Firebase Hosting, Auth, etc.), the official way to access Firestore in Node.js is through the Firebase Admin SDK, which comes from the firebase-admin package.

• Firestore is a part of Firebase — even though it's also deeply integrated into Google Cloud, Firestore originated as the Firebase real-time database successor.

• The Firebase Admin SDK is Google’s recommended way to interact with Firestore from server-side Node.js, including:

  • Google App Engine

  • Cloud Functions

  • Cloud Run

  • Compute Engine

  • Local dev environments

NOTE if you had a specific serviceAccount (see below about default in GAE) access how to intialize

/*Set up Admin API for Firebase*/
const admin = require('firebase-admin');
//Define path to secret key generated for service account
const serviceAccount = require(PATH TO KEY);
//Initialize the app
admin.initializeApp({
  credential: admin.credential.cert(serviceAccount)
});

Different General Code Snippet - to save

let db = admin.firestore()    
//Depending on your schema, save data by specifying the collection name, 
//document name and data contents as follows  
await db.collection(key).doc(prod).set(save_to_database[key][prod])

Different General Code Snippet -- to read/retrieve data

//Get all docs under the given mycollection
helper_func_get_data = async (mycollection, db) => {
    const data = await db.collection(mycollection).get()
    if(data.empty)
        {
            return -1
        }
    else return data

 }

Step 5: Create app.yaml for GAE Standard

runtime: nodejs20  # or nodejs18
instance_class: F1

env_variables:
  GOOGLE_NODE_RUNFILES: "1"

note:

instance_class: F1

This controls the size and cost of each App Engine instance. It's optional, but important if you want to manage performance and billing.

• F1 is the smallest, cheapest, and free-tier eligible (ideal for testing or small traffic).

What is GOOGLE_NODE_RUNFILES: "1"?

This is a special GAE setting used with Node.js apps. It tells App Engine to include node_modules binaries and runtime files when packaging your app.

• It’s helpful for compatibility and ensures that dependencies (especially those that rely on compiled binaries like firebase-admin) run properly.

• Without this, certain modules may behave unexpectedly in some edge cases.

You usually don’t need to touch this unless troubleshooting issues — but including it is safe and ensures maximum compatibility.

Step 6: Deploy to GAE

Make sure you're authenticated with Google Cloud SDK:

gcloud auth login
gcloud config set project [YOUR_PROJECT_ID]  
gcloud app deploy  

Visit your app after deployment:

gcloud app browse  

Credentails

GAE uses Application Default Credentials, so you don’t need to set up a service account key

Application Default Credentials (ADC) are a way for Google Cloud services (like App Engine, Cloud Functions, etc.) to automatically authenticate to other Google Cloud APIs (like Firestore) without you needing to explicitly create and download service account keys.

Why You Don’t Need to Set Up a Service Account Key on GAE?

When you deploy your app to Google App Engine, Google automatically runs it in a secure, isolated environment with a default service account attached.

This means:

• Your code can call admin.initializeApp() (for Firebase Admin SDK), and it will automatically use the App Engine’s identity to authenticate.

• You don’t need to use admin.initializeApp({ credential }) with a downloaded JSON key file.

• It's safer, because you’re not managing credentials manually.

The Default Identity: App Engine Default Service Account

When running on App Engine, your app uses this service account by default. This account is automatically created with your project.

[PROJECT_ID]@appspot.gserviceaccount.com

---

Permission to Access Firestore

Your App Engine default service account must have IAM permissions to access Firestore — most commonly:

• Cloud Datastore User role (legacy, still applies to Firestore)

• or Cloud Firestore User, Cloud Firestore Viewer, or Editor roles

• Make sure your App Engine service account has permission to access Firestore (should be enabled by default).

How to Check and Set Permissions

1. Go to the IAM page in Google Cloud Console.

2. Find the service account:

   [PROJECT_ID]@appspot.gserviceaccount.com    
       

3. Ensure it has one of the following roles:

   • Cloud Datastore User (this gives read/write access to Firestore in Native mode as well)

   • OR Editor (if you need broad permissions during development)

You can add a role by:

• Clicking the pencil/edit icon next to the service account.

• Clicking Add another role.

• Searching for and selecting Cloud Datastore User or another appropriate role.

NOTE:

What Does await Do in JavaScript?

await is a keyword in JavaScript that can only be used inside an async function. It tells the program to wait for a Promise to complete before continuing.

const result = await someAsyncFunction();

• someAsyncFunction() returns a Promise.

• await pauses execution of the current async function until the Promise is resolved (success) or rejected (error).

• The resolved value gets stored in result.

• If the Promise is rejected, the error can be caught using try...catch.