feat(dev): add local development setup — one-command startup, contributor guide, and bug fixes by JoelJosephPhilip · Pull Request #1163 · vicharanashala/vibe

JoelJosephPhilip · 2026-07-18T13:40:31Z

Summary

This PR adds a complete local development setup so new contributors can clone the repo and get the full stack running with a single command — no manual MongoDB install, no real Firebase project needed.

Problem

Right now, a new contributor who clones this repo has no clear path to run it locally:

README.md Quick Start says only "Documentation in progress"
backend/.example.env has NODE_ENV=production and points to MongoDB Atlas
There is no startup script — contributors must figure out the stack manually
Signup fails with a MongoDB transaction error on standalone MongoDB instances
Login fails because the backend calls the real Firebase API instead of the local emulator

What's Included

One-command startup scripts

Script	Platform
`run-all.ps1`	Windows (PowerShell)
`run-all.sh`	macOS / Linux (Bash)

Both scripts automatically:

Validate prerequisites (Node.js, pnpm, Java, Firebase CLI) with clear install hints
Create backend/.env from .example.env if it does not exist
Auto-fix Firebase project ID mismatches between backend/.env and backend/.firebaserc
Ensure FIREBASE_AUTH_EMULATOR_HOST is set so login routes to the local emulator
Install dependencies and launch the full stack

# Windows — after cloning
powershell -ExecutionPolicy Bypass -File .\run-all.ps1

# macOS / Linux — after cloning
chmod +x run-all.sh && ./run-all.sh

`local_development_run_guide.md` (new)

Complete contributor guide covering:

Prerequisites table with install links
Quick-start commands for all platforms
How to set up env files manually
Architecture diagram (mermaid)
Three documented local dev bugs and their fixes
Full troubleshooting section

`README.md` — Quick Start updated

Replaced "Documentation in progress" with actual one-line commands for both Windows and macOS/Linux.

`backend/.example.env` (updated)

Was broken for local development:

Field	Before	After
`NODE_ENV`	`production`	`development`
`DB_URL`	`mongodb+srv://...` (Atlas)	`mongodb://localhost:27017/vibe`
`APP_MODULE`	`auth`	`all`
Firebase config	Incomplete	Full emulator config with correct project ID

`frontend/.env.example` (new)

Pre-filled with safe local dev placeholder values. The Firebase Auth Emulator ignores the API key, so contributors do not need a real Firebase project.

`cli/src/ui.ts` (new) + `cli/src/commands/start.ts` (updated)

Pretty terminal UI for vibe start:

ASCII art banner on startup
Colored step logger with status icons (✓ ◌ ✗ ⚠)
Live service status board showing all running services with their URLs
Zero extra dependencies — ANSI escape codes only

Bug Fixes for Local Dev

Fix 1 — Signup fails: MongoDB transaction error

Error:

MongoServerError: Transaction numbers are only allowed on a replica set member or mongos

mongodb-memory-server runs a standalone instance that does not support transactions. Added a dev-mode fallback in BaseService._withTransaction() that retries the operation without a transaction when a standalone instance is detected.

Production is unaffected — Atlas always runs as a replica set where transactions work normally.

Fix 2 — Login fails: backend calls real Firebase instead of emulator

Error: Backend fetches https://identitytoolkit.googleapis.com with no API key in dev mode.

AuthController.login() now checks FIREBASE_AUTH_EMULATOR_HOST and routes sign-in requests to the local emulator (http://127.0.0.1:9099) instead of the real Firebase API.

Fix 3 — Firebase emulator project ID mismatch

Warning:

Multiple projectIds are not recommended in single project mode.
Requested project ID vibe-dev-d6279, but the emulator is configured for vibe-5b35a.

The startup scripts auto-detect and fix mismatches between backend/.env and backend/.firebaserc on every run.

Testing

Verified on Windows 11, Node.js v22, pnpm, Java 21, Firebase CLI:

POST /api/auth/signup  →  { userId: "..." }   ✅
POST /api/auth/login   →  { idToken: "..." }  ✅  (token issued by Firebase emulator)
GET  /health           →  { status: "ok" }    ✅
Frontend http://localhost:5173                 ✅

Files Changed

File	Change
`run-all.ps1`	NEW
`run-all.sh`	NEW
`local_development_run_guide.md`	NEW
`frontend/.env.example`	NEW
`cli/src/ui.ts`	NEW
`backend/.example.env`	UPDATED
`README.md`	UPDATED
`cli/src/commands/start.ts`	UPDATED
`backend/src/shared/classes/BaseService.ts`	FIX
`backend/src/modules/auth/controllers/AuthController.ts`	FIX
`.gitignore`	FIX — track `.env.example` template files

- Add run-all.ps1 (Windows) and run-all.sh (macOS/Linux) one-command startup scripts that validate prerequisites, auto-bootstrap backend/.env from .example.env, auto-fix Firebase project ID mismatches, install dependencies, and launch the full local stack (MongoDB + Firebase Auth Emulator + Backend + Frontend) - Add local_development_run_guide.md: complete contributor guide covering prerequisites, quick-start commands for all platforms, env file setup, architecture diagram, documented bug fixes for local dev, and a full troubleshooting section - Update README.md Quick Start section with one-line commands for both Windows and macOS/Linux - Update backend/.example.env: pre-configured for local dev (NODE_ENV= development, local DB_URL, APP_MODULE=all, full Firebase emulator config) so new contributors can cp .example.env .env and start immediately - Add frontend/.env.example: new file with safe local dev placeholder values (Firebase Auth Emulator accepts any API key) - Fix backend/.gitignore to track .env.example and .example.env template files while still ignoring real .env files - Fix cli/src/commands/start.ts: add pretty terminal UI with ASCII art banner, colored step logger, service status board, and styled ready messages using new cli/src/ui.ts helper (zero extra dependencies) - Fix backend/src/shared/classes/BaseService.ts: add dev-mode fallback for MongoDB transactions on standalone instances (avoids crash on mongodb-memory-server which does not support replica-set transactions) - Fix backend/src/modules/auth/controllers/AuthController.ts: route login requests to Firebase Auth Emulator when FIREBASE_AUTH_EMULATOR_HOST is set, instead of calling the real Firebase API

Copilot

Pull request overview

This PR introduces a one-command local development experience for the ViBe monorepo, aiming to help new contributors run the full stack locally (MongoDB, Firebase Auth emulator, backend API, and frontend) with minimal manual setup.

Changes:

Add cross-platform startup scripts (run-all.ps1, run-all.sh) plus a detailed local development guide and README quick-start updates.
Enhance the CLI vibe start experience (MongoDB Memory Server auto-start, emulator bootstrapping, and terminal UI/status output).
Fix local-dev backend issues: MongoDB transaction fallback for standalone instances and routing login to the Firebase Auth emulator when configured.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
run-all.sh	New macOS/Linux startup script that validates prerequisites, bootstraps backend env, installs deps, and starts the stack.
run-all.ps1	New Windows startup script with the same responsibilities as `run-all.sh`.
README.md	Replaces “Documentation in progress” with concrete local quick-start commands and a link to the local dev guide.
local_development_run_guide.md	Adds a comprehensive contributor-facing local development guide and troubleshooting notes.
frontend/.env.example	Adds a frontend env template with emulator-friendly placeholder Firebase values and local API base URL.
cli/src/ui.ts	Adds terminal UI helpers (banner, step logging, and a “service board”).
cli/src/commands/start.ts	Expands `vibe start` to auto-start MongoDB Memory Server, run emulators/services, and show UI output.
backend/src/shared/classes/BaseService.ts	Adds a standalone MongoDB transaction fallback for local dev.
backend/src/modules/auth/controllers/AuthController.ts	Routes login to the Firebase Auth emulator when `FIREBASE_AUTH_EMULATOR_HOST` is set; otherwise uses real Identity Toolkit.
backend/.example.env	Updates backend env template for local dev defaults (local MongoDB, emulator config, and placeholders).
.gitignore	Adjusts ignore rules to allow committing `*.env.example` and `.example.env` templates.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+if [ -f "$BACKEND_FIREBASERC" ]; then
+  # Extract the "default" project using basic shell parsing (no jq required)
+  EMULATOR_PROJECT_ID=$(grep -o '"default": *"[^"]*"' "$BACKEND_FIREBASERC" | sed 's/"default": *"\([^"]*\)"/\1/')
+fi


+        if (
+          typeof error?.message === 'string' &&
+          error.message.includes(REPLICA_SET_REQUIRED_MSG)
+        ) {
+          console.warn(
+            '[BaseService] Standalone MongoDB detected – running operation ' +
+              'without a transaction (dev-mode only).',
+          );
+          return operation(null as unknown as ClientSession);
+        }


+  // After a delay, refresh the board showing services as "up"
+  const markUp = (name: string) => {
+    const svc = services.find((s) => s.name === name);
+    if (svc) svc.status = "up";
+  };


+    const name   = clr.bwhite(svc.name.padEnd(22));
+    const row    = `  │  ${name} ${statusStr.padEnd(6)}  ${urlStr}`;
+    const padding = " ".repeat(Math.max(0, 52 - stripAnsi(row).length + 2));
+    console.log(col(C.cyan + C.bold, `  │`) + `  ${name} ${statusStr}   ${urlStr}${padding}` + col(C.cyan + C.bold, `│`));


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 18, 2026 13:40

github-actions Bot added docs Improvements or additions to documentation frontend Changes to the frontend of the project backend labels Jul 18, 2026

Copilot started reviewing on behalf of JoelJosephPhilip July 18, 2026 13:40 View session

Copilot AI reviewed Jul 18, 2026

View reviewed changes

Potential fix for pull request finding

c8f7d7b

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Navigation Menu

feat(dev): add local development setup — one-command startup, contributor guide, and bug fixes - #1163

feat(dev): add local development setup — one-command startup, contributor guide, and bug fixes#1163
JoelJosephPhilip wants to merge 2 commits into
vicharanashala:mainfrom
JoelJosephPhilip:feat/local-dev-setup

JoelJosephPhilip commented Jul 18, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

JoelJosephPhilip commented Jul 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Problem

What's Included

One-command startup scripts

local_development_run_guide.md (new)

README.md — Quick Start updated

backend/.example.env (updated)

frontend/.env.example (new)

cli/src/ui.ts (new) + cli/src/commands/start.ts (updated)

Bug Fixes for Local Dev

Fix 1 — Signup fails: MongoDB transaction error

Fix 2 — Login fails: backend calls real Firebase instead of emulator

Fix 3 — Firebase emulator project ID mismatch

Testing

Files Changed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JoelJosephPhilip commented Jul 18, 2026 •

edited

Loading

`local_development_run_guide.md` (new)

`README.md` — Quick Start updated

`backend/.example.env` (updated)

`frontend/.env.example` (new)

`cli/src/ui.ts` (new) + `cli/src/commands/start.ts` (updated)