| name | scaffolding-nextjs-foundation |
| description | Generates a new Next.js application with Tailwind, TypeScript, and modern dependencies based on audit specifications. Use when beginning the scaffolding phase of a greenfield codebase rewrite. |
Objective
Establish the baseline directory structure and dependencies for the modern rewrite of the legacy application.
Instructions for the Scaffold Subagents
Copy this checklist and track your progress:
Task Progress:
- [ ] Step 1: Initialize Next.js
- [ ] Step 2: Initialize UI
- [ ] Step 3: Install Core Dependencies
- [ ] Step 4: Clean the Scaffold
- [ ] Step 5: Verification
Step 1. Initialize Next.js
Execute the create-next-app command in the designated modernization directory (usually the root of the new repo).
* Command: npx -y create-next-app@latest . --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
* Note: Ensure you are running this in the correct output directory (e.g., modern-app/) and not inside the legacy legacy-app/ folder.
Step 2. Initialize UI
Run npx shadcn@latest init to set up Tailwind CSS and the components directory.
Step 3. Install Core Dependencies
Evaluate the Business_Logic_Rules.md artifact (found in docs/legacy-audit/). Based on those rules, install the necessary modern replacements explicitly using the @latest tag so the 10-year old versions are avoided.
* MongoDB & Auth Connection: If connecting to legacy MongoDB, install mongodb@latest.
* Connection Secret: Plan for the .env.local initialization.
* CRITICAL: When the modern-app runs on the host (e.g., npm run dev), it cannot resolve internal Docker hostnames like mongo. You MUST use localhost (e.g., mongodb://localhost:27017/db_name) to bridge onto the exposed container port.
* Auth Strategy Selection:
* If mongodb@7+ is used: Do NOT install @auth/mongodb-adapter (it currently has peer conflicts with v7). Instead, use a JWT strategy (next-auth@latest) and the native driver for manual account/user lookups in the authorize callback.
* If mongodb@^6 is acceptable: Install mongodb@^6 and @auth/mongodb-adapter@latest.
* Additional Packages:
* For payload validation, install zod@latest.
* For legacy Mongoose methods like password hashing, install bcrypt@latest and -D @types/bcrypt@latest.
* Command Example (MongoDB 7 / JWT): npm install next-auth@latest mongodb@latest zod@latest bcrypt@latest && npm install -D @types/bcrypt@latest
Step 4. Clean the Scaffold
Remove default boilerplate from src/app/page.tsx and src/app/globals.css to create a blank canvas for the next subagents.
Step 5. Verification
Ensure npm run build succeeds on the empty foundation.
