用途:为 monday code 应用启动开发服务器并搭建本地环境,适用于用户要求启动开发服务器、运行前端(Vite)、运行后端(Express watch 模式)、同时运行前后端,或为 Document DB 搭建本地 MongoDB 的场景。
主要能力与用法:先检测项目结构,执行 ls -d frontend/ backend/ 2>/dev/null 判断是前端、后端还是全栈应用。随后做预检:若缺少 node_modules 则在对应目录执行 npm install;检查 backend/.env 是否存在,缺失时提示警告。后端所需环境变量包括 MONDAY_CLIENT_SECRET(用于 JWT 校验,在 Developer Center > OAuth 设置)与 MNDY_MONGODB_CONNECTION_STRING(本地示例 mongodb://localhost:27017/appname)。若后端使用 MongoDB,可用 docker run -d --name monday-app-mongo -p 27017:27017 mongo:7 启动本地实例。启动命令:前端 cd frontend && npm run dev(Vite,端口 3000,支持 HMR);后端 cd backend && npm run dev(Express,端口 8080 或 PORT 环境变量,tsx watch 自动重载);全栈建议先启动后端再启动前端,或开两个终端。
本地开发检测:前端 MondayContext 通过判断不在 monday.com iframe 内且处于 Vite DEV 模式来识别本地开发,此时 SDK 调用返回模拟数据(test-user-1、test-account-1),API 调用使用 VITE_DEV_TOKEN,无需真实 monday.com 连接。
与 monday.com 联调:需在 Developer Center 创建应用及功能。前端可用本地地址 http://localhost:3000 作为部署 URL;后端如需真实 webhook/集成,需隧道,例如 mapps tunnel:create -p 8080,再把隧道 URL 填入 Developer Center 的 Features > 部署 > External hosting。
限制与排错:端口占用可用 lsof -ti:3000 | xargs kill 或改端口;缺 node_modules 需 npm install;Docker 未运行需先启动 Docker Desktop;缺 .env 可从 .env.example 复制或手动创建;MONDAY_CLIENT_SECRET 需从 Developer Center 获取;前端空白页需检查控制台并确认 Vite 运行在 3000 端口。