@xfe-repo/web-app 2.0.0-beta.1 → 2.0.0-beta.2

package/README.md

@@ -35,7 +35,65 @@ export const page = app.registerPage(config, Component)
 }
 ```
 
-`renderMode: "client"` 生成 SPA 静态产物 `build/client/index.html`；`xfe-web start` 使用框架内的 Express 静态服务，支持 `basename` 下的深链接回退，缺失的 `/assets` 文件仍返回 404，不需要 server bundle 或运行时 JWT 私钥。现有 Docker 启动命令无需修改，也可把 `build/client` 交给外部静态托管并配置 index.html 回退。`"server"`（兼容旧项目的默认值）保留服务端构建与 React Router 服务；切换为 SSR 前仍需实现请求隔离的 Store/Context。其他可选项：`basename`、`host`、`lang`（默认 `zh-CN`）、`themeColor`。`HOST/PORT` 环境变量可覆盖 SPA 启动地址。修改启动配置后重新运行 CLI。
+`renderMode: "client"` 生成 SPA 静态产物 `dist/client/index.html`；`xfe-web start` 使用框架内的 Express 静态服务，支持 `basename` 下的深链接回退，缺失的 `/assets` 文件仍返回 404，不需要 server bundle 或运行时 JWT 私钥。现有 Docker 启动命令无需修改，也可把 `dist/client` 交给外部静态托管并配置 index.html 回退。`"server"`（兼容旧项目的默认值）保留服务端构建与 React Router 服务；切换为 SSR 前仍需实现请求隔离的 Store/Context。其他可选项：`basename`、`host`、`lang`（默认 `zh-CN`）、`themeColor`。`HOST/PORT` 环境变量可覆盖 SPA 启动地址。修改启动配置后重新运行 CLI。
+
+构建目录通过 `xfe.json.webapp.buildDirectory` 配置，省略时统一输出到 `dist`。SPA 产物位于 `<buildDirectory>/client`，SSR 额外生成 `<buildDirectory>/server/index.js`；`xfe-web build/start/config` 使用同一配置，无需移动产物或修改隐藏的 React Router/Vite 配置。
+
+```json
+{
+  "webapp": {
+    "buildDirectory": "dist"
+  }
+}
+```
+
+升级注意：此前默认目录为 `build`。部署或脚本仍使用旧路径的项目可显式设置 `"buildDirectory": "build"`，待相关路径一起调整后再移除配置。目录必须是项目内独立的相对路径，也支持 `artifacts/web` 这样的多级目录；不能指向项目根目录、项目外或 `src/types/public/node_modules/.git`。输出目录及其上级不能是符号链接。构建会清空目标目录，请勿放入需要保留的文件；修改配置后需要重新构建。
+
+框架 Docker 模板默认复制 `dist`。`xfe-web config` 会把配置后的相对路径写入 Drone 镜像构建参数 `XFE_BUILD_DIRECTORY`；使用模板手动构建镜像时，需传入与 `xfe.json` 相同的路径，例如 `docker build --build-arg XFE_BUILD_DIRECTORY=artifacts/web -f deploy/Dockerfile .`。仅更新目录配置时，需重新生成流水线配置并同步模板。
+
+可选 Node 入口：
+
+```json
+{
+  "webapp": {
+    "serverEntry": "src/server.ts",
+    "buildDirectory": "dist",
+    "renderMode": "client"
+  }
+}
+```
+
+`serverEntry` 是项目内默认导出服务工厂的 TypeScript / JavaScript ESM 文件：
+
+```ts
+import { createServer } from 'node:http'
+import type { NodeServerFactory } from '@xfe-repo/web-app/dist/node'
+
+/** 业务先处理自己的请求，剩余请求交给框架前端。 */
+const createApplication: NodeServerFactory = ({ frontend }) => ({
+  server: createServer(
+    /** API、认证、Host 检查可在这里先于前端执行。 */ (request, response) => {
+      if (request.url === '/healthz') {
+        response.end('ok')
+        return
+      }
+      frontend(request, response)
+    },
+  ),
+})
+
+export default createApplication
+```
+
+命令仍是 `xfe-web dev/build/start`。开发时后端由 `tsx watch` 监督应用进程重启，前端复用现有 Vite / React Router 配置；HTTP、业务 WebSocket 与 HMR 使用同一个端口、同一个应用 Node 进程（开发监听器由 tsx 维护）。页面变化继续走 Vite HMR，不重启业务实例；后端变化通过退出信号关闭旧进程、释放资源，再由 tsx 创建新进程；开发报错后继续监听，源码修复后重新启动。开发进程读取 Vite 约定的 `.env` 文件，已有环境变量优先。
+
+工厂接收 `frontend`（原生 Node 请求处理器）和 `mode`（`development` / `production`），返回未监听的 `http.Server`。可选 `upgrade(request, socket, head)` 处理业务 WebSocket；框架先分流保留的 `<basename>/_xfe/hmr`，其余升级再交给业务。WebSocket 库使用 `noServer` 模式，不要自行给 server 注册 `upgrade` 事件；业务处理器应关闭不接受的升级连接。可选异步 `close()` 在 HTTP 排空后释放数据库等资源。工厂内初始化尚未返回就失败时，由工厂回收自己已取得的资源。
+
+框架负责唯一的 `listen`、SIGINT / SIGTERM 和关闭流程；入口不要自行监听端口或接管进程退出。生产停机时普通 HTTP 请求最多等待 30 秒排空；开发重启超时遵循 tsx 的原生行为，升级连接在后端重载及停机时断开。自定义入口通过 `HOST/PORT` 或 `webapp.host/port` 设置地址，不接收额外 CLI 参数。
+
+构建先生成前端，再输出 `<buildDirectory>/server/node.mjs` 和 sourcemap，SSR 模式不覆盖 React Router 的 `server/index.js`；SPA 模式清理预渲染的 server 中间产物。`xfe-web start` 只加载产物，部署无需源码或隐藏生成缓存。业务 Node 依赖保持 external，必须放在业务 `dependencies`；通过 `xfe-web start` 启动时 `@xfe-repo/web-app` 也必须保留在生产依赖中。生产地址和密钥通过进程环境传入，启动不读取开发 `.env`。
+
+`src/app.server.ts` 继续只负责 React Router 请求 middleware，不能替代 `serverEntry`。省略 `serverEntry` 的项目保留原有 SPA / SSR 分支。此最小版本不提供自定义打包插件、任意服务端多入口或生产热重载；后端重启交给 tsx，不维护进程内模块缓存或热重载状态机。
 
 原生扩展保持兼容：已有 `src/root.tsx` 优先于默认根布局；其中的 Framework value exports 使用直接的 `export const/function/class` 声明。原生 `route.tsx` 和标准导出仍可使用，其 API 和类型同样从 `@xfe-repo/web-router` 导入，不要求业务另装 React Router。
 
@@ -59,7 +117,7 @@ xfe-web config
 `dev` 和 SSR `start` 获取完整 JWT 环境，SPA `start` 不获取私钥；
 `build` 只向客户端注入 aud/keyId，明确丢弃私钥。
 
-SSR `start` 使用与构建一致的隐藏工作目录，使官方 serve 正确解析 `build/client` 静态资源；启动时仅保证该目录存在，不读取 `src/pages` 或重新生成入口。
+SSR `start` 使用与构建一致的隐藏工作目录，使官方 serve 正确解析 `dist/client` 静态资源；启动时仅保证该目录存在，不读取 `src/pages` 或重新生成入口。
 
 构建会先加载 `react-app-polyfill/stable`，并在应用原有 browserslist 的基础上，补充 Edge 18、Chrome 64、Firefox 60、Safari/iOS 12 及以上的 JS 编译目标，业务代码和第三方依赖使用同一目标。
 

package/deploy/.drone.yml

@@ -59,6 +59,8 @@ steps:
       password:
         from_secret: password
       dockerfile: deploy/Dockerfile
+      build_args:
+        - "XFE_BUILD_DIRECTORY=dist"
       repo_path: xhj-prod-registry-vpc.cn-hangzhou.cr.aliyuncs.com/xhj-image/
       repo_name: ${DRONE_REPO}
       tags:
@@ -161,6 +163,11 @@ steps:
       - set +x
       - printf '%s' "$PASSWORD" | helm registry login xhj-prod-registry-vpc.cn-hangzhou.cr.aliyuncs.com --username "$USERNAME" --password-stdin
       - helm push "$chartName-$chartVersion.tgz" oci://xhj-prod-registry-vpc.cn-hangzhou.cr.aliyuncs.com/xhj-image
+      - >-
+        curl -i --fail-with-body
+        https://deploy.eshetang.com/deploy.v1.DeployExternalService/UpdateGitOpsChartVersion
+        -H 'Content-Type: application/json'
+        -d "{\"service\":\"$${chartName}\",\"chartVersion\":\"$${chartVersion}\"}"
     when:
       ref:
         include:

package/deploy/Dockerfile

@@ -6,8 +6,9 @@ ENV NODE_ENV=production
 ENV HOST=0.0.0.0
 ENV PORT=3000
 
-COPY build ./build
-COPY deploy/static ./build/client
+ARG XFE_BUILD_DIRECTORY=dist
+COPY ["${XFE_BUILD_DIRECTORY}", "./${XFE_BUILD_DIRECTORY}"]
+COPY ["deploy/static", "./${XFE_BUILD_DIRECTORY}/client"]
 COPY deploy/modules ./node_modules
 COPY package.json xfe.json ./