Scaffold Next.js Project

# Scaffold Next.js Project Use this skill when starting a new web project. This is James's standard stack: Next.js + Prisma 7 + Neon + Tailwind + Vercel + Cloudflare DNS. ## Prerequisites - Node.js 22+, npm/npx available - `vercel` CLI authenticated (`vercel whoami`) - `neonctl` CLI authenticated (`neonctl --version`) - `gh` CLI authenticated (`gh auth status`) - Access to vault proxy for Cloudflare DNS (`BOTS_VAULT_ADMIN_TOKEN`) ## Quick Reference Table | Task | Command | |------|---------| | Create Next.js app | `npx create-next-app@latest myapp --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm` | | Init git | `git init` | | Create GitHub repo | `gh repo create worklocalinc/myapp --private --source=. --remote=origin` | | Install Prisma | `npm install prisma @prisma/client @prisma/adapter-pg pg && npm install -D @types/pg dotenv` | | Init Prisma | `npx prisma init` | | Create Neon project | `neonctl projects create --name myapp --region-id aws-us-east-1 --org-id org-patient-sunset-05785270` | | Get pooled URL | `neonctl connection-string --project-id <id> --pooled` | | Get direct URL | `neonctl connection-string --project-id <id>` | | Run migrations | `npx prisma migrate dev --name init` | | Generate client | `npx prisma generate` | | Deploy to Vercel | `vercel --yes --prod` | | Add env var to Vercel | `vercel env add DATABASE_URL production` | | Add Vercel domain | `vercel domains add myapp.skynet.ceo` | | Create DNS CNAME | `curl -X POST ... vault proxy cloudflare dns_records` | | Verify DNS | `dig myapp.skynet.ceo` | | First commit | `git add -A && git commit -m "Initial scaffold"` | ## Core Workflows ### Workflow 1: Create the Project ```bash cd ~/dev/projects npx create-next-app@latest my-project \ --typescript --tailwind --eslint --app --src-dir \ --import-alias "@/*" --use-npm cd my-project ``` Initialize git and GitHub: ```bash git init gh repo create worklocalinc/my-project --private --source=. --remote=origin ``` Verify: `gh repo view worklocalinc/my-project` shows the repo. ### Workflow 2: Set Up Prisma 7 + Neon 1. Install dependencies: ```bash npm install prisma @prisma/client @prisma/adapter-pg pg npm install -D @types/pg dotenv npx prisma init ``` 2. Create Neon database: ```bash neonctl projects create --name my-project --region-id aws-us-east-1 --org-id org-patient-sunset-05785270 ``` 3. Add to `.env`: ``` DATABASE_URL="postgresql://...pooler URL...?sslmode=require" DIRECT_URL="postgresql://...direct URL...?sslmode=require" ``` 4. Update `prisma/schema.prisma`: ```prisma generator client { provider = "prisma-client" output = "../src/generated/prisma" } datasource db { provider = "postgresql" } ``` 5. Create `prisma.config.ts`: ```typescript import "dotenv/config"; import { defineConfig } from "prisma/config"; export default defineConfig({ schema: "prisma/schema.prisma", datasource: { url: process.env["DIRECT_URL"] || process.env["DATABASE_URL"], }, }); ``` 6. Create `src/lib/db.ts`: ```typescript import { PrismaPg } from "@prisma/adapter-pg"; import { PrismaClient } from "@/generated/prisma/client"; import { Pool } from "pg"; const pool = new Pool({ connectionString: process.env.DATABASE_URL }); const adapter = new PrismaPg(pool); const globalForPrisma = globalThis as unknown as { prisma: PrismaClient }; export const prisma = globalForPrisma.prisma || new PrismaClient({ adapter }); if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma; ``` 7. Run migrations: ```bash npx prisma migrate dev --name init npx prisma generate ``` Verify: `npx prisma studio` opens without errors. ### Workflow 3: Apply Dark Theme In `src/app/globals.css`: ```css @import "tailwindcss"; body { @apply bg-gray-950 text-gray-100 antialiased; } ``` Standard color palette: - Background: `bg-gray-950` (page), `bg-gray-900` (cards), `bg-gray-800` (inputs) - Accent: `cyan-400` / `cyan-500` (primary), `emerald-400` (success), `red-400` (error) - Borders: `border-gray-800` (default), `border-cyan-500/30` (active) - Text: `text-gray-100` (primary), `text-gray-400` (secondary), `text-gray-600` (muted) ### Workflow 4: Deploy to Vercel + Custom Domain 1. Deploy: ```bash vercel --yes --prod vercel env add DATABASE_URL production vercel env add DIRECT_URL production ``` 2. Add custom domain: ```bash vercel domains add myapp.skynet.ceo ``` 3. Create DNS record via vault proxy: ```bash source .env curl -s -X POST \ -H "Authorization: Bearer $BOTS_VAULT_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ "http://192.168.86.27:8020/v1/proxy/cloudflare/zones/a2ecd4cf8341dc3e8e105dc06c14d2fc/dns_records" \ -d '{"type":"CNAME","name":"myapp.skynet.ceo","content":"cname.vercel-dns.com","proxied":true,"ttl":1}' ``` Verify: `dig myapp.skynet.ceo` resolves within 1-5 minutes. ### Workflow 5: Create CLAUDE.md and First Commit Every project needs a `CLAUDE.md` with: - Project name and purpose - Tech stack - Key commands (dev, build, deploy) - Database info and Neon project ID - API endpoints - Deployment URL Then commit: ```bash cat >> .gitignore << 'EOF' node_modules/ .env .env.local src/generated/ EOF npx prisma generate git add -A git commit -m "Initial scaffold: Next.js + Prisma 7 + Neon + Tailwind" git push -u origin main ``` ## Common Patterns **Standard API route:** ```typescript // src/app/api/items/route.ts import { NextRequest, NextResponse } from "next/server"; import { prisma } from "@/lib/db"; export async function GET(request: NextRequest) { const items = await prisma.item.findMany(); return NextResponse.json(items); } ``` **Seed script in package.json:** ```json { "prisma": { "seed": "npx tsx prisma/seed.ts" } } ``` ## Troubleshooting - **Symptom**: `npx prisma generate` fails with "Cannot find module" **Cause**: Generated client not yet created or `output` path wrong in schema **Fix**: Run `npx prisma generate` after any schema change. Ensure `src/generated/` is in `.gitignore`. - **Symptom**: Vercel build fails with "Can't reach database server" **Cause**: `DATABASE_URL` not set in Vercel environment variables **Fix**: Run `vercel env add DATABASE_URL production` and redeploy. - **Symptom**: Custom domain not resolving after 10+ minutes **Cause**: DNS CNAME not created or Cloudflare hasn't propagated **Fix**: Verify with `dig myapp.skynet.ceo`. Re-run the vault proxy CNAME creation if missing. - **Symptom**: Prisma migrate fails on Vercel build **Cause**: Vercel runs `prisma generate` at build time but can't run migrations **Fix**: Never run `prisma migrate` in the build step. Run migrations locally with `DIRECT_URL`, then deploy. ## References - Next.js docs: https://nextjs.org/docs - Prisma 7 docs: https://www.prisma.io/docs - Vercel CLI: https://vercel.com/docs/cli - Neon CLI: https://neon.tech/docs/reference/cli-install - manage-cloudflare-dns skill for DNS setup details - manage-neon-database skill for Neon details