Run Nexu Seed Scripts to Load Lesson Content into Firestore

Nexu lesson content — lessons, blocks, and questions — lives in Firestore, not in the application bundle. Seed scripts are the mechanism the development team uses to write that content from local JSON files into the shared Firebase project nexu-156ce. This page covers how authentication works for seeds, how to run them for the first time on a new machine, and how to diagnose common errors.

Three distinct authentication layers

Seed scripts use a completely different authentication mechanism than the Nexu app. Understanding the distinction prevents hours of debugging.

┌─────────────────────────────────────────────────────────────────┐
│  YOUR GOOGLE ACCOUNT (Owner/Editor on console.firebase.google.com) │
└───────────────────────────────┬─────────────────────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        ▼                       ▼                       ▼
 npx firebase login    gcloud auth application-    npm run seed:lesson1
                       default login
        │                       │                       │
        │                       │                       │
 Authenticates the       Stores Application         Reads local JSON files
 Firebase CLI (deploy,   Default Credentials        and writes them to
 firebase use, emulators) so Node.js scripts        Firestore in nexu-156ce
                         (firebase-admin) can
                         act on your behalf

Layer	Tool	Used by
Firebase CLI (`npx firebase login`)	Firebase CLI	`firebase deploy`, `firebase use`, emulators
Application Default Credentials (`gcloud auth application-default login`)	Google Cloud SDK	Node.js seed scripts via `firebase-admin`
Firebase Auth (email/password)	Firebase Auth	App users logging in through the browser

The seed script does not use the Firebase Auth session from the browser, and the browser app never runs the seed. The seed uses applicationDefault() from firebase-admin, which reads the credentials created by gcloud auth application-default login.

Prerequisites

Before running seeds on a new machine, ensure the following are installed and available in your PATH:

Node.js 18+ and npm
Google Cloud SDK (gcloud command) — install instructions
A Google account with Owner or Editor role in Firebase project nexu-156ce — verify in Firebase Console → Project Settings → Users and permissions

First-time setup on a new machine

Install frontend dependencies

From the repository root:

npm install

This installs the React app’s dependencies. Seed-script dependencies (firebase-admin) are installed separately and automatically when you run a seed command.

npx firebase login

A browser window opens. Sign in with the team Google account that has Owner or Editor access to nexu-156ce. Then set the active project so all firebase commands target Nexu:

npx firebase use nexu-156ce

Authenticate Application Default Credentials

gcloud auth application-default login

A browser window opens. Sign in with the same team Google account used in the previous step. This stores credentials at ~/.config/gcloud/application_default_credentials.json (Linux/macOS) or %APPDATA%\gcloud\application_default_credentials.json (Windows). The seed-lesson.mjs script reads these credentials via applicationDefault() from firebase-admin.

This step is required once per machine (or after the credentials expire or you switch accounts).

Run the lesson seed

npm run seed:lesson1

Expected output:

Eliminando datos previos de lesson_01_higiene_personal...
Insertando lección, bloques y preguntas...
Listo (lesson_01): 1 lección, 8 bloques, 23 preguntas.
lessonId: lesson_01_higiene_personal

(Optional) Deploy rules if changed

Only needed if you edited firestore.rules or firestore.indexes.json:

npm run firebase:deploy:rules

See Firebase Rules for full details.

Start the app

npm run dev

The app reads lesson data from the shared Firebase project nexu-156ce, which now contains the seeded content. Navigate to /ruta after registering or logging in to see Lesson 1.

Available seed commands

Command	Script invoked	What it seeds
`npm run seed:lesson1`	`node scripts/seed-lesson.mjs 01`	Deletes and re-uploads Lesson 1 from `firestore-seed/lesson_01/`
`npm run seed:lesson2`	`node scripts/seed-lesson.mjs 02`	Deletes and re-uploads Lesson 2 from `firestore-seed/lesson_02/`

Both commands first run npm install --prefix scripts to ensure firebase-admin is installed in the scripts/ directory before executing the seed. This keeps seed dependencies isolated and out of the Vercel build.

What the seed script does internally

The single parameterized script scripts/seed-lesson.mjs performs the following steps every time it runs:

Validates inputs — checks that a two-digit lesson key was provided (e.g., 01) and that the corresponding firestore-seed/lesson_XX/ directory exists with lesson.json, blocks.json, and questions.json.
Initializes firebase-admin — calls initializeApp({ credential: applicationDefault(), projectId: 'nexu-156ce' }). This is why Application Default Credentials are required.
Deletes existing data for the target lesson:
- All documents in lessons/{lessonId}/blocks/
- All documents in lessons/{lessonId}/questions/
- The root lessons/{lessonId} document
Writes new data from the local JSON files:
- lesson.json → one document at lessons/{lessonId}
- blocks.json → one document per block at lessons/{lessonId}/blocks/{blockId}
- questions.json → one document per question at lessons/{lessonId}/questions/{questionId}
Warns if isActive is false in lesson.json, since an inactive lesson will not appear in the /ruta learning path.

What the seed does NOT touch

Running a seed is safe for the following data — it will never be modified or deleted:

User accounts (/users/{uid})
User lesson progress (/users/{uid}/lessonProgress/)
Certificates (/certificates/ and /certificatePublic/)
Firestore security rules (firestore.rules) — deploy those separately with npm run firebase:deploy:rules
Vercel hosting or any other lesson’s content

The seed overwrites lesson content in the shared Firebase project nexu-156ce. Every developer on the team and every user of the production app reads from this same database. Running npm run seed:lesson1 will replace Lesson 1’s content for everyone simultaneously — including any active users in the middle of a session.Always coordinate with the team in your group chat before running a seed, especially for Lesson 1 which is already live.

Common errors and fixes

Could not load the default credentials

The seed script could not find Application Default Credentials on this machine.Fix: Run the following and complete the browser login with the team Google account (Owner/Editor on nexu-156ce):

gcloud auth application-default login

Then re-run npm run seed:lesson1.

PERMISSION_DENIED

Your Google account authenticated successfully but does not have sufficient permissions to write to Firestore in project nexu-156ce.Fix: Ask a project owner to verify your account in Firebase Console → Project Settings → Users and permissions. Your email must appear with the Owner or Editor role. The email must match exactly the account you used for gcloud auth application-default login.

ERR_PNPM_OUTDATED_LOCKFILE on Vercel

A dependency in package.json was added or changed without updating pnpm-lock.yaml. Vercel requires the lockfile to be in sync before it will run pnpm install.Fix: Run the following locally and commit the updated lockfile:

pnpm install --lockfile-only
git add pnpm-lock.yaml
git commit -m "chore: sync pnpm lockfile"
git push

Note: scripts/package.json uses npm and has no effect on pnpm-lock.yaml.

Lesson not appearing in the app after seed

The seed completed without errors but the lesson does not show up on the /ruta learning path.Fix — check isActive: Open firestore-seed/lesson_XX/lesson.json and confirm "isActive": true. If it is false, the seed script itself will print a warning. Update the JSON and re-run the seed.Fix — check project ID: Open .env.local and confirm VITE_FIREBASE_PROJECT_ID=nexu-156ce. If this variable is missing or points to a different project, the app is querying a Firestore database that the seed did not touch.

firebase: command not found

The Firebase CLI is not installed globally, or it is not in your system PATH.Fix: Never rely on a globally installed firebase binary. Always use the npx-based commands provided in package.json:

# Instead of: firebase login
npx firebase login

# Instead of: firebase use nexu-156ce
npx firebase use nexu-156ce

# To deploy rules:
npm run firebase:deploy:rules

The npm run firebase:deploy:rules script already uses npx firebase-tools internally, so it works regardless of global installs.

Get Started

Architecture

Lessons

Certificates

Deployment

Run Nexu Seed Scripts to Load Lesson Content into Firestore

Three distinct authentication layers

Prerequisites

First-time setup on a new machine

Available seed commands

What the seed script does internally

What the seed does NOT touch

Common errors and fixes

Build docs developers (and LLMs) love

Get Started

Architecture

Lessons

Certificates

Deployment

Documentation Index

​Three distinct authentication layers

​Prerequisites

​First-time setup on a new machine

​Available seed commands

​What the seed script does internally

​What the seed does NOT touch

​Common errors and fixes

Build docs developers (and LLMs) love

Three distinct authentication layers

Prerequisites

First-time setup on a new machine

Available seed commands

What the seed script does internally

What the seed does NOT touch

Common errors and fixes