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

package/README.md

@@ -1,6 +1,123 @@
 # `@xfe-repo/web-app`
 
-web框架基础库
+统一管理 Web 配置、页面入口、类型检查与构建；当前内部使用 React Router 8 Framework Mode 和 Vite 8。
+
+要求 Node.js `>=22.22.0`、React/ReactDOM `>=19.2.7`。业务项目只维护：
+
+- `src/layout.tsx`（可选），只编写业务 Provider 与布局，接收 `children`
+- `src/app.ts`，服务端上下文存在时再增加 `src/app.server.ts`
+- `src/pages/**/index.tsx`
+- `xfe.json.webapp`
+
+`react-router.config`、Vite 配置由 app 包维护，路由收集器由 `@xfe-repo/web-router/routes` 维护；CLI 在 `node_modules/.cache/xfe-web/react-router`
+生成 React Router 必需的隐藏 shim。`home/index.tsx`、`index/index.tsx` 和旧的
+`_index/index.tsx`/`route.tsx` 映射 `/`；页面目录支持 `$id`、`[id]` 动态参数。普通页面只需：
+
+不能直接把隐藏 app 生成到 `@xfe-repo/web-app` 包目录：React Router 会按物理路径发现 config/routes，dev watcher 和 typegen 还会向相邻目录写入状态；共享包目录既不属于业务项目，也会让多个项目互相覆盖。项目本地的 `node_modules/.cache` 可写、默认忽略，且仍处于依赖解析范围内。
+
+客户端与服务端复用已锁定版本的 React Router 官方默认 entry，业务项目不再维护 entry 文件；服务端入口由 CLI 显式转发，避免底层工具向业务清单添加 `isbot` 并自动安装。HTML 文档、路由出口与默认 loading/error 由框架生成。
+
+`vite`、`less` 和 `isbot` 由本包安装和维护；SSR 产物打包 `isbot`，不要求部署项目另装它。`react-router` 由本包与 `web-router` 固定为同一版本，业务从 `@xfe-repo/web-router` 导入路由 API 和类型，无需直接声明这四个依赖。
+
+```tsx
+export const page = app.registerPage(config, Component)
+```
+
+默认使用框架的 404/500 边界，业务无需创建 `pages/$`；可在 `layout.tsx` 直接导出 `ErrorView({ error })` 自定义错误展示。
+
+```json
+{
+  "webapp": {
+    "renderMode": "client",
+    "title": "商户后台",
+    "port": 3001
+  }
+}
+```
+
+`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。
+
+命令保持不变：
+
+```bash
+xfe-web dev
+xfe-web build
+xfe-web typegen
+xfe-web typecheck
+xfe-web start
+xfe-web config
+```
+
+`typecheck` 先在与 dev/build 相同的隐藏目录生成路由类型，再运行 TypeScript。项目 tsconfig 继承 `@xfe-repo/web-app/tsconfig.json`，只保留业务别名和源码范围；客户端环境类型引用 `@xfe-repo/web-app/client`，无需配置生成类型的路径。重复生成只更新内容变化的文件，不删除正在运行的开发缓存。
+
+业务 `package.json` 的类型检查脚本使用 `"typecheck": "xfe-web typecheck"`；类型声明文件加入 `/// <reference types="@xfe-repo/web-app/client" />`，不再直接配置 `vite/client` 或隐藏缓存的 `rootDirs/include`。
+
+框架将 React、ReactDOM、React Redux 与 RTK 去重到消费应用的依赖，支持 workspace 和本地链接联调。React 组件仍依赖 React；这里隔离的是路由和构建实现，不承诺任意 UI 技术栈之间零修改迁移。
+
+`dev` 和 SSR `start` 获取完整 JWT 环境，SPA `start` 不获取私钥；
+`build` 只向客户端注入 aud/keyId，明确丢弃私钥。
+
+SSR `start` 使用与构建一致的隐藏工作目录，使官方 serve 正确解析 `dist/client` 静态资源；启动时仅保证该目录存在，不读取 `src/pages` 或重新生成入口。
 
 构建会先加载 `react-app-polyfill/stable`，并在应用原有 browserslist 的基础上，补充 Edge 18、Chrome 64、Firefox 60、Safari/iOS 12 及以上的 JS 编译目标，业务代码和第三方依赖使用同一目标。
 

package/client.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/deploy/.drone.yml

@@ -18,17 +18,19 @@ resources:
 steps:
   - name: install
     pull: if-not-exists
-    image: xhj-prod-registry-vpc.cn-hangzhou.cr.aliyuncs.com/xhj-image-common/node-base:20.17.0-pnpm
+    image: node:22.22.0-bookworm
     volumes:
       - name: node-modules
         path: /drone/src/node_modules
     commands:
+      - corepack enable
+      - corepack prepare pnpm@10.30.3 --activate
       - pnpm config set registry https://registry.npmmirror.com
       - pnpm i
 
   - name: build
     pull: if-not-exists
-    image: xhj-prod-registry-vpc.cn-hangzhou.cr.aliyuncs.com/xhj-image-common/node-base:20.17.0-pnpm
+    image: node:22.22.0-bookworm
     resources:
       limits:
         memory: 8192MiB
@@ -36,11 +38,16 @@ steps:
       - name: node-modules
         path: /drone/src/node_modules
     commands:
+      - corepack enable
+      - corepack prepare pnpm@10.30.3 --activate
       - cp -r node_modules/@xfe-repo/web-app/deploy deploy
       - export NODE_OPTIONS="--max-old-space-size=8192"
-      - export REACT_APP_RELEASE=$DRONE_REPO_NAME@${DRONE_TAG:CI_COMMIT_SHA}
-      - echo -n "$REACT_APP_RELEASE" > deploy/static/release
+      - export XFE_RELEASE=$DRONE_REPO_NAME@${DRONE_TAG:CI_COMMIT_SHA}
+      - export REACT_APP_RELEASE=$XFE_RELEASE
+      - printf '%s' "$XFE_RELEASE" > deploy/static/release
+      - cp deploy/static/release deploy/static/check-update
       - pnpm build
+      - cp -a node_modules deploy/modules
 
   - name: image-build
     image: xhj-prod-registry-vpc.cn-hangzhou.cr.aliyuncs.com/image-common/kaniko:latest
@@ -52,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:

package/deploy/Dockerfile

@@ -1,10 +1,19 @@
-FROM xhj-prod-registry-vpc.cn-hangzhou.cr.aliyuncs.com/xhj-image-common/nginx-base
+FROM node:22.22.0-bookworm-slim
 
-WORKDIR /code/www/deploy/webroot/app/current
+WORKDIR /app
 
-COPY build/client ./
+ENV NODE_ENV=production
+ENV HOST=0.0.0.0
+ENV PORT=3000
 
-COPY deploy/nginx.conf /etc/nginx/conf.d/default.conf
+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 ./
 
-# 拷贝静态文件
-COPY deploy/static ./
+EXPOSE 3000
+
+USER node
+
+CMD ["./node_modules/.bin/xfe-web", "start"]

package/deploy/helm/templates/deployment.yaml

@@ -30,8 +30,12 @@ spec:
             requests:
               cpu: "0.01"
               memory: "100Mi"
-          {{if $.Values.hostPrefix}}
           env:
+            - name: HOST
+              value: "0.0.0.0"
+            - name: PORT
+              value: "3000"
+          {{if $.Values.hostPrefix}}
             - name: HOST_PREFIX
               value: "{{ $.Values.hostPrefix }}"
           {{end}}
@@ -40,21 +44,4 @@ spec:
             - configMapRef:
                 name: "app-common-config"
           {{- end }}
-          volumeMounts:
-            - mountPath: /var/log/nginx
-              subPath: "xfe/{{ $.Values.app }}"
-              name: log
-          command:
-            - bash
-            - "-c"
-            - |
-              nginx
-              while :
-              do
-              sleep 10
-              done
-      volumes:
-        - name: log
-          hostPath:
-            path: /var/log
 ---

package/deploy/helm/templates/svc.yaml

@@ -9,4 +9,4 @@ spec:
   ports:
     - port: 80
       name: http
-      targetPort: 80
+      targetPort: 3000