การพัฒนาบนเครื่อง · Local development

สิ่งที่ต้องมี#

• Node.js 22+ (Wrangler 4 ไม่รองรับ Node 20; Next.js เองรันได้ตั้งแต่ 20.9) แนะนำติดตั้งผ่าน nvm
• npm (lockfile คือ package-lock.json)
• ไม่จำเป็นต้องมี OpenAI key — ไม่มี key แอปจะใช้ offline planner

ติดตั้ง#

git clone <repo> nvx-stack-builder && cd nvx-stack-builder
npm install            # postinstall รัน scripts/patch-opennext.mjs อัตโนมัติ
cp .env.example .env.local        # สำหรับ next dev (ถ้าต้องการ AI)
cp .dev.vars.example .dev.vars    # สำหรับ wrangler preview (ถ้าต้องการ AI)

postinstall patch adapter ของ OpenNext ให้รองรับ preview-props.json ของ Next 16.4 ถ้าเห็น [patch-opennext] pattern not found แปลว่า adapter เปลี่ยนเวอร์ชันแล้ว ให้ตรวจว่ายังต้อง patch หรือไม่ (ดู cloudflare-runtime.md)

สองวิธีรัน และควรใช้เมื่อไร#

ข้อสังเกตจากประสบการณ์: next dev บางครั้งแสดง CSS ค้าง (stale) หลังแก้ token มาก ๆ ให้ยืนยันภาพด้วย npm run preview ก่อนสรุปผลเสมอ

npm run preview = opennextjs-cloudflare build && opennextjs-cloudflare preview build ใช้เวลาประมาณ 1 นาที ถ้าต้องการรัน preview ซ้ำโดยไม่ build ใหม่: npx opennextjs-cloudflare preview --port 8787 ปิด preview ที่ค้าง: pkill -f "opennextjs-cloudflare preview"; pkill -f workerd

ชุดตรวจก่อน commit#

npm run lint
npm run typecheck
npm test
npm run docs:check
npm run cf:build      # ต้องผ่านก่อน deploy

การทดสอบในเบราว์เซอร์ (แนะนำเมื่อแก้ UI)#

ใช้ Playwright เปิด http://localhost:8787 แล้วตรวจ: ทุกหน้าได้ 200, /templates/unknown ได้ 404, document.documentElement.scrollWidth <= innerWidth ที่ 1440px และ 390px ทั้งภาษาไทย (localStorage.nvx-lang = "th") และอังกฤษ, ไม่มี console error, flow ของ builder (เลือกเทมเพลต → ลาก → ลบ → ดาวน์โหลด → share link) ภาพหน้าจอเก็บใน screenshots/v<x>/

โครงสร้างที่ควรรู้#

ดู file-map.md จุดเริ่มอ่านโค้ดที่ดี: src/lib/composer.ts → src/components/builder.tsx → src/app/api/plan/route.ts

ปัญหาที่พบบ่อย#

• wrangler บอกว่า Node เก่าเกินไป → ใช้ Node 22+
• พอร์ต 8787 ถูกใช้ → ปิด preview เก่าตามคำสั่งข้างบน
• AI ไม่ทำงานใน dev → ตรวจว่า OPENAI_API_KEY อยู่ใน .env.local หรือ .dev.vars และตรงรูปแบบ ^[\w-]{20,400}$; GET /api/plan จะบอก serverKeyConfigured
• ได้ 429 ระหว่างทดสอบ → เกิน 20 POST/นาทีจาก IP เดียว (limiter ในหน่วยความจำรีเซ็ตเมื่อ restart server)