Streamlined Next.js + Firebase monorepo for student capstone projects — batteries included, beginner friendly, free-tier only.
New here? Read the step-by-step guide — it walks you from clone to shipping your first feature. The system diagrams are in docs/ARCHITECTURE.md.
Note for the PR if you cannot merge your pr is because there is a high veulnerability and the system doesn't allow for pr with high vulnerabilities to be merged. Instructions are below to fix this.
| Frontend | Next.js 16 (App Router) · React 19 · TypeScript 5 · Tailwind v4 |
| Backend | Firebase Cloud Functions v2 · Express (single "fat lambda") |
| Database / Auth | Firestore · Firebase Authentication (free Spark plan) |
| Package manager | pnpm workspaces — always pnpm, never npm/yarn |
| Testing | Vitest · Testing Library · supertest |
| Quality gates | Lefthook (Conventional Commits, lint, format) · GitHub Actions CI |
There's no local emulator and no Docker — the app always talks to a real (free) Firebase project. Firebase Cloud Storage isn't used either, since real usage requires the paid Blaze plan; store file metadata in Firestore or use a free third-party host if a feature needs uploads.
- Node.js 22 — nodejs.org
- pnpm —
npm install -g pnpm - No Firebase CLI install needed —
npx firebase-toolsruns it on demand for rule deploys
git clone https://github.com/your-org/garage-boilerplate my-project
cd my-project
pnpm run bootstrapEasiest path: open the project in Claude Code and run
/bootstrap— it does everything below, walks you through creating a free Firebase project, handles the common failure modes, and finishes with a verified auth smoke test.
Bootstrap installs dependencies, creates the root .env from .env.example (only if missing), and generates the per-package env files.
All env values live in the root .env. frontend/.env.local and backend/.env are generated from it by pnpm run env:sync (runs automatically before pnpm run dev) — never edit them by hand.
Create a project at console.firebase.google.com — the free Spark plan is enough, no billing required — then:
- Enable Authentication (Email/Password + Google) and create a Firestore database
- Register a web app (Project settings → Your apps → Web) and copy each
firebaseConfigvalue into the matchingNEXT_PUBLIC_FIREBASE_*variable in.env - Generate a service account key (Project settings → Service accounts), base64-encode it, and set
FIREBASE_SERVICE_ACCOUNT_KEY_BASE64in.env:# macOS (BSD base64 — no -w flag) base64 -i service-account.json | tr -d '\n' # Linux (GNU base64) base64 -w 0 service-account.json # Windows PowerShell (single quotes around the path) [Convert]::ToBase64String([IO.File]::ReadAllBytes('C:\path\to\service-account.json'))
- Set
NEXT_PUBLIC_FIREBASE_PROJECT_IDin.envand the same id in.firebaserc(projects.default)
Full variable reference: docs/ENV-VARS.md.
pnpm run dev- App → http://localhost:3000
Restart the dev server after changing .env — NEXT_PUBLIC_* variables are baked in at startup.
| Symptom | What to try |
|---|---|
auth/invalid-api-key |
Fill every NEXT_PUBLIC_FIREBASE_* value in the root .env, run pnpm run env:sync, then restart the dev server. |
| "Firebase web config is incomplete" on Vercel | A NEXT_PUBLIC_FIREBASE_* env var is missing in Vercel. Add it under Project Settings → Environment Variables (same names as your local .env), then redeploy — existing deployments don't pick up new env vars automatically. See docs/CI-CD.md § Vercel Setup. |
Invalid project id: REPLACE_WITH_... |
Set the real project id in .firebaserc. |
'next' is not recognized / Command "next" not found |
Run pnpm install from the repo root. If it persists, delete all node_modules folders and reinstall. |
| Ignored build scripts warning from pnpm | Build approvals live in pnpm-workspace.yaml (allowBuilds) — re-run pnpm install. |
| "Missing or insufficient permissions" | Firestore security rules don't allow that access — add rules in firebase/firestore.rules, then deploy them (npx firebase-tools deploy --only firestore:rules). |
| Commit rejected | Message must be Conventional Commits (feat: …, fix: …). |
More beginner-oriented pitfalls: docs/GUIDE.md § Common pitfalls.
/
├── frontend/ Next.js 16 App Router
│ └── src/
│ ├── app/ Pages (route groups: (auth), (dashboard))
│ ├── components/ UI components (layout, shared)
│ ├── features/ Feature modules (one folder per business domain)
│ ├── lib/ Firebase client/admin (lazy init), validations, utils
│ ├── hooks/ Custom React hooks
│ ├── providers/ React context providers
│ ├── actions/ Next.js Server Actions
│ └── types/ TypeScript type definitions
├── backend/ Cloud Functions v2 — Express fat-lambda
│ └── src/
│ ├── app.ts Express app factory
│ ├── routes/ One file per resource
│ ├── middleware/ auth (ID token → req.user), errorHandler (RFC 9457)
│ └── lib/ firebase (Admin singleton), errors (HttpError), zodConverter
├── firebase/ Firestore rules, indexes
├── docs/ Guides and reference docs — start with GUIDE.md
└── .claude/ Claude Code harness (agents, skills, MCP, hooks)
pnpm run bootstrap # First-time: install deps, env templates
pnpm run dev # Frontend dev server (talks to your real Firebase project)
pnpm run build # Build all packages
pnpm run test # Backend unit tests (mocked Firebase Admin)
pnpm run test:component # Frontend unit tests
pnpm run test:all # All tests
pnpm run lint # ESLint across all packages
pnpm run format # Prettier across all packages
pnpm run typecheck # TypeScript check across all packages
pnpm run env:sync # Regenerate frontend/backend env files from root .env
pnpm run validate # Check for unreplaced template placeholdersSecurity is enforced in independent layers — Claude Code guard hooks, HTTP hardening (helmet/CORS/rate limits), token + session-cookie auth, Zod input validation, default-deny Firestore rules, and CI scanning (pnpm audit). See docs/SECURITY.md.
pnpm audit currently flags two high-severity CVEs — both transitive, dev/build-time only, not runtime-reachable:
| Package | Issue | Pulled in by |
|---|---|---|
js-yaml |
CVE-2026-59870 — quadratic CPU DoS on !!omap resolution |
eslint's dependency chain (lint-time only) |
nanoid |
Infinite loop when a custom generator's size is 0 |
postcss, used by Tailwind/Next/Vitest builds (build-time only) |
To patch: add these two lines under overrides: in pnpm-workspace.yaml, then run pnpm install:
js-yaml: '^4.3.1'
nanoid: '^3.3.17'Confirm with pnpm audit — should show 0 high/critical findings.
| Branch | Purpose |
|---|---|
main |
Production — protected, no direct pushes |
feature/* |
New features → PR back to main |
hotfix/* |
Urgent fixes → PR back to main |
Use the Claude Code skills /git-feature, /git-hotfix, /git-release. Details: docs/GIT-WORKFLOW.md.
The repo ships a pre-configured harness: three MCP servers (context7 for live library docs, firebase for Firestore/deploy tooling, stitch for design-to-code), three sub-agents (security-reviewer, doc-auditor, test-writer), enforcement hooks (blocks any, secret prefixes, direct pushes to main, unapproved deploys), and skills for scaffolding and quality:
| Category | Skills |
|---|---|
| Setup | /bootstrap — guided end-to-end local setup with verification |
| Scaffolding | /new-feature · /new-page · /new-component · /firebase-collection · /add-auth-provider · /add-route · /evolve-schema · /add-env-var |
| Quality | /verify · /checkpoint · /save-session · /resume-session |
| Git | /git-feature · /git-hotfix · /git-release |
See CLAUDE.md for the full harness reference.
| Topic | Link |
|---|---|
| Beginner guide (start here) | docs/GUIDE.md |
| Verified walkthrough (all steps + code) | docs/TUTORIAL-WALKTHROUGH.md |
| Copy-paste setup (no AI, exact steps) | docs/COPY-PASTE-SETUP.md |
| Copy-paste feature build (no AI, exact file paths) | docs/COPY-PASTE-FEATURE.md |
| Slide deck — system overview + AI tooling | docs/garage-boilerplate-guide.pptx |
| Slide deck — the notes feature, step by step | docs/notes-feature-tutorial.pptx |
| Architecture + diagrams | docs/ARCHITECTURE.md |
| Frontend conventions | docs/FRONTEND.md |
| Backend conventions | docs/BACKEND.md |
| Design system | docs/DESIGN.md |
| Firestore schema | docs/FIRESTORE-SCHEMA.md |
| Environment variables | docs/ENV-VARS.md |
| Testing | docs/TESTING.md |
| Security | docs/SECURITY.md |
| Git workflow | docs/GIT-WORKFLOW.md |
| CI/CD & deployment | docs/CI-CD.md |
The frontend deploys to Vercel (free Hobby tier, no billing account needed — this app is server-rendered, so it needs a server host, not static hosting). Use this to depoy to Vercel - DEPLOY-TO-VERCEL.md
Follow the checklist in CLAUDE.md — Forking for a New Client Project, then run pnpm run validate to confirm no template placeholders remain.
Original boilerplate by Duc Gia Tin Huynh (LinkedIn).