@lark-apaas/coding-template-vite-react 0.1.0-alpha.1 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-template-vite-react",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0",
   "description": "Vite + React client template for miaoda coding",
   "type": "module",
   "files": ["template", "hooks"],

package/template/.spark_project

@@ -0,0 +1,12 @@
+run = ["npm", "run", "dev"]
+lint = ["npm", "run", "lint"]
+hidden = [".config", ".git", "scripts", "node_modules", "dist", ".spark", ".agent", ".agents", "tmp", ".spark_project", ".playwright-cli"]
+
+[deployment]
+build = ["npm", "run", "build"]
+
+[files]
+[files.restrict]
+pathPatterns = ["package.json", ".spark_project", ".spark/meta.json", ".gitignore"]
+[files.hidden]
+pathPatterns = [".config", ".git", "scripts", "node_modules", "dist", ".spark", ".agent", ".agents", "tmp", ".spark_project", ".playwright-cli"]

package/template/README.md

@@ -15,7 +15,7 @@
 ## 目录结构
 
 ```
-client/src/
+src/
 ├── index.tsx            # 入口（勿修改）
 ├── app.tsx              # 路由配置（仅在 <Routes> 内增删 <Route>）
 ├── index.css            # 全局样式 + 主题变量
@@ -51,8 +51,8 @@ shared/
 
 | 文件 | 原因 |
 |------|------|
-| `client/src/index.tsx` | Provider 层级 + 样式引入，由模板管理 |
-| `client/src/components/ui/*` | shadcn/ui 内置组件，版本锁定 |
+| `src/index.tsx` | Provider 层级 + 样式引入，由模板管理 |
+| `src/components/ui/*` | shadcn/ui 内置组件，版本锁定 |
 
 ---
 
@@ -60,10 +60,10 @@ shared/
 
 | 内容类型 | 放置位置 |
 |---------|---------|
-| 新页面 | `client/src/pages/<PageName>/PageName.tsx` |
-| 页面专属组件 | `client/src/pages/<PageName>/components/` |
-| 自定义 Hooks | `client/src/hooks/` |
-| 工具函数 | `client/src/lib/` |
+| 新页面 | `src/pages/<PageName>/PageName.tsx` |
+| 页面专属组件 | `src/pages/<PageName>/components/` |
+| 自定义 Hooks | `src/hooks/` |
+| 工具函数 | `src/lib/` |
 | 静态数据文件 | `shared/static/data/` |
 | 静态图片 | `shared/static/images/` |
 
@@ -72,7 +72,7 @@ shared/
 ## 导入路径
 
 ```typescript
-// @/ 别名 → client/src/
+// @/ 别名 → src/
 import { cn } from "@/lib/utils";
 import { useIsMobile } from "@/hooks/use-mobile";
 
@@ -85,14 +85,14 @@ import configData from "@shared/static/config.json";
 
 ## 路由配置
 
-- 新增页面需在 `client/src/app.tsx` 的 `<Routes>` 内注册 `<Route>`
+- 新增页面需在 `src/app.tsx` 的 `<Routes>` 内注册 `<Route>`
 - `BrowserRouter` 已在 `index.tsx` 中配置，`app.tsx` 中**禁止**再包裹 Router
 
 ---
 
 ## 主题变量
 
-主题色定义在 `client/src/index.css`，通过 `:root` CSS 变量 + `@theme inline` 注册到 Tailwind。
+主题色定义在 `src/index.css`，通过 `:root` CSS 变量 + `@theme inline` 注册到 Tailwind。
 
 | 用途 | Tailwind 类 | CSS 变量 |
 |------|------------|----------|

package/template/components.json

@@ -5,7 +5,7 @@
   "tsx": true,
   "tailwind": {
     "config": "",
-    "css": "client/src/index.css",
+    "css": "src/index.css",
     "baseColor": "neutral",
     "cssVariables": true,
     "prefix": ""

package/template/package.json

@@ -3,10 +3,11 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
+    "dev": "node scripts/dev.mjs",
     "build": "bash scripts/build.sh",
     "typecheck": "tsc -p tsconfig.app.json",
     "lint": "concurrently npm:typecheck npm:lint:eslint",
-    "lint:eslint": "eslint client/src"
+    "lint:eslint": "eslint src"
   },
   "dependencies": {
     "@hookform/resolvers": "^5.2.2",
@@ -36,7 +37,7 @@
     "@radix-ui/react-toggle": "^1.1.9",
     "@radix-ui/react-toggle-group": "^1.1.10",
     "@radix-ui/react-tooltip": "^1.1.18",
-    "@lark-apaas/client-toolkit-lite": "^1.1.0",
+    "@lark-apaas/client-toolkit-lite": "1.1.7-alpha.17",
     "@formkit/auto-animate": "^0.9.0",
     "@gsap/react": "^2.1.2",
     "framer-motion": "^12.38.0",
@@ -54,6 +55,7 @@
     "react": "^19.2.4",
     "react-day-picker": "^9.14.0",
     "react-dom": "^19.2.4",
+    "react-error-boundary": "^6.0.0",
     "react-hook-form": "^7.72.0",
     "react-resizable-panels": "^4.7.6",
     "react-router-dom": "^7.13.2",
@@ -71,7 +73,7 @@
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "@lark-apaas/coding-presets": "^1.0.0",
-    "@lark-apaas/coding-vite-preset": "^1.0.0",
+    "@lark-apaas/coding-vite-preset": "1.0.7-alpha.13",
     "concurrently": "^9",
     "eslint": "^9",
     "eslint-plugin-react-hooks": "^7",

package/template/scripts/dev.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * Dev launcher: 启动 vite dev server，把 stdout/stderr 加时间戳前缀
+ * 写到 logs/<name>.std.log + 当前 stdout；负责子进程组管理与端口孤儿清理。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { spawn, execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+process.chdir(ROOT);
+
+const LOG_DIR = process.env.LOG_DIR || 'logs';
+const CLIENT_DEV_PORT = process.env.CLIENT_DEV_PORT || '8001';
+
+fs.mkdirSync(LOG_DIR, { recursive: true });
+
+function timestamp() {
+  const now = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return (
+    `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ` +
+    `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`
+  );
+}
+
+function log(msg) {
+  const line = `[${timestamp()}] [dev] ${msg}\n`;
+  try { process.stdout.write(line); } catch {}
+}
+
+/** 清理端口占用：lsof -ti:<port> | kill -9 */
+function killOrphansByPort(port) {
+  try {
+    const out = execSync(`lsof -ti:${port}`, { stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .trim();
+    if (!out) return [];
+    const pids = out.split('\n').filter(Boolean);
+    for (const pid of pids) {
+      try {
+        process.kill(Number(pid), 'SIGKILL');
+        log(`killed orphan pid=${pid} on :${port}`);
+      } catch {}
+    }
+    return pids;
+  } catch {
+    return [];
+  }
+}
+
+const managed = [];
+
+function startProcess({ name, command, args, logFileName }) {
+  const logFd = logFileName
+    ? fs.openSync(path.join(LOG_DIR, logFileName), 'a')
+    : null;
+
+  const child = spawn(command, args, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: false,
+    cwd: ROOT,
+    env: process.env,
+    detached: true,
+  });
+
+  const pipeLines = (stream) => {
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    rl.on('line', (line) => {
+      const msg = `[${timestamp()}] [${name}] ${line}\n`;
+      try { process.stdout.write(msg); } catch {}
+      if (logFd != null) {
+        try { fs.writeSync(logFd, msg); } catch {}
+      }
+    });
+  };
+  pipeLines(child.stdout);
+  pipeLines(child.stderr);
+
+  managed.push({ name, child });
+  return child;
+}
+
+killOrphansByPort(CLIENT_DEV_PORT);
+
+startProcess({
+  name: 'client',
+  command: 'npx',
+  args: ['vite', '--port', CLIENT_DEV_PORT, '--host', '0.0.0.0'],
+  logFileName: 'client.std.log',
+});
+
+let stopping = false;
+function cleanup(signal) {
+  if (stopping) return;
+  stopping = true;
+  log(`cleanup triggered by ${signal}`);
+
+  for (const { child } of managed) {
+    if (!child.pid) continue;
+    try { process.kill(-child.pid, signal || 'SIGTERM'); } catch {}
+  }
+  setTimeout(() => {
+    for (const { child } of managed) {
+      if (!child.pid) continue;
+      try { process.kill(-child.pid, 'SIGKILL'); } catch {}
+    }
+    killOrphansByPort(CLIENT_DEV_PORT);
+    process.exit(0);
+  }, 2000);
+}
+
+process.on('SIGINT', () => cleanup('SIGTERM'));
+process.on('SIGTERM', () => cleanup('SIGTERM'));
+// pkill 杀父 npm 后会收 SIGHUP（controlling tty 关闭）；
+// Node 默认直接退出不跑 handler，注册 handler 触发 cleanup
+process.on('SIGHUP', () => cleanup('SIGTERM'));
+
+Promise.race(
+  managed.map(({ child }) => new Promise((r) => child.on('exit', r))),
+).then(() => cleanup('SIGTERM'));

package/template/shared/capabilities/README.md

@@ -0,0 +1,5 @@
+# shared/capabilities/
+
+Capabilities 声明目录。此处文件描述应用对外暴露的能力，由平台运行时消费。
+
+具体 schema 与编写规范见 steering（`.agent/steering/`）。占位目录，按需添加。

package/template/shared/static/README.md

@@ -0,0 +1,16 @@
+# shared/static/
+
+⚠️ **此目录资源经鉴权访问**——由平台托管在私有源，仅登录用户可拉取。请勿放公开资源。
+
+## 与其他资源目录的区分
+
+| 目录 | 访问 | 部署目标 | 适用场景 |
+|---|---|---|---|
+| `src/assets/` | 代码 `import` | 随 JS 一起进 CDN | 图标、被组件 import 的小图（多数情况选这里） |
+| `public/` | 公网匿名可访问 | 公网 CDN | favicon、被外部按固定 URL 引用的资源 |
+| `shared/static/` | 需应用鉴权 | 私有源 | 仅登录用户可见的图片、PDF、配置文件等 |
+
+## 引用方式
+
+`shared/static/` 下文件**不要**用 `/shared/static/foo.png` 这种相对路径直接引用——浏览器无法匿名访问。
+应通过平台运行时 SDK 拿到带 token 的 URL 后再使用。

package/template/{client/src → src}/hooks/use-mobile.ts

@@ -3,7 +3,9 @@ import * as React from "react"
 const MOBILE_BREAKPOINT = 768
 
 export function useIsMobile() {
-  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+  const [isMobile, setIsMobile] = React.useState<boolean>(() =>
+    typeof window !== "undefined" && window.innerWidth < MOBILE_BREAKPOINT,
+  )
 
   React.useEffect(() => {
     const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
@@ -11,9 +13,8 @@ export function useIsMobile() {
       setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
     }
     mql.addEventListener("change", onChange)
-    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
     return () => mql.removeEventListener("change", onChange)
   }, [])
 
-  return !!isMobile
+  return isMobile
 }

package/template/{client/src → src}/index.tsx

@@ -1,7 +1,8 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { BrowserRouter } from "react-router-dom";
-import { AppContainer } from "@lark-apaas/client-toolkit-lite";
+import { ErrorBoundary } from "react-error-boundary";
+import { AppContainer, ErrorRender } from "@lark-apaas/client-toolkit-lite";
 import App from "./app";
 import "./index.css";
 
@@ -9,7 +10,13 @@ createRoot(document.getElementById("root")!).render(
   <StrictMode>
     <BrowserRouter basename={process.env.CLIENT_BASE_PATH || "/"}>
       <AppContainer>
-        <App />
+        <ErrorBoundary
+          fallbackRender={({ error, resetErrorBoundary }) => (
+            <ErrorRender error={error} resetErrorBoundary={resetErrorBoundary} />
+          )}
+        >
+          <App />
+        </ErrorBoundary>
       </AppContainer>
     </BrowserRouter>
   </StrictMode>,

package/template/tsconfig.app.json

@@ -4,10 +4,10 @@
     "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
     "baseUrl": ".",
     "paths": {
-      "@/*": ["./client/src/*"],
+      "@/*": ["./src/*"],
       "@shared/*": ["./shared/*"]
     }
   },
-  "include": ["client/src", "shared"],
-  "exclude": ["client/src/components/ui"]
+  "include": ["src"],
+  "exclude": ["src/components/ui"]
 }

package/template/tsconfig.json

@@ -2,7 +2,7 @@
   "compilerOptions": {
     "baseUrl": ".",
     "paths": {
-      "@/*": ["./client/src/*"],
+      "@/*": ["./src/*"],
       "@shared/*": ["./shared/*"]
     }
   },

package/template/vite.config.ts

@@ -2,10 +2,9 @@ import path from 'path'
 import { defineConfig } from '@lark-apaas/coding-vite-preset'
 
 export default defineConfig({
-  root: path.resolve(__dirname, 'client'),
   resolve: {
     alias: {
-      '@': path.resolve(__dirname, 'client/src'),
+      '@': path.resolve(__dirname, 'src'),
       '@shared': path.resolve(__dirname, 'shared'),
     },
   },