@lark-apaas/coding-preset-vite-react 0.1.1-alpha.0 → 0.1.1

package/dist/index.d.ts

@@ -1,320 +0,0 @@
-import { Plugin, Connect, UserConfig } from 'vite';
-
-interface RoutesPluginOptions {
-    /** 应用入口路径（相对项目根）。默认按顺序探测 `src/app.tsx`、`client/src/app.tsx`。 */
-    appPath?: string;
-    /** 写入 routes.json 时给每条 path 的前缀。未传时回退到 `process.env.CLIENT_BASE_PATH`。 */
-    basePath?: string;
-    /** dev middleware 把 `/routes.json` 挂在哪个 URL 前缀下。未传时回退到 `process.env.CLIENT_BASE_PATH`。 */
-    serveBasePath?: string;
-}
-interface RouteEntry {
-    path: string;
-}
-/**
- * AST 解析 React Router 的 `<Route>` 元素，返回路由列表。
- *
- * 算法移植自 `@lark-apaas/devtool-kits` 的 `parseRoutesFromFile`：
- *   - `<Route path="..." />` / `path={'...'}` / `path={`...`}` 都识别
- *   - 嵌套 path 自动 join，子节点用绝对路径时覆盖
- *   - `<Route index>` 视作当前层级根
- *   - `path="*"` 通配符跳过
- *   - 表达式形如 `path={variable}` 时跳过（无法静态求值）
- */
-declare function parseRoutes(source: string, basePath: string): RouteEntry[];
-declare function routesPlugin(options?: RoutesPluginOptions): Plugin;
-
-/**
- * 压缩 HTML，同时保护 HBS（Handlebars）占位符。
- *
- * `{{csrfToken}}` / `{{{appAvatar}}}` 这类占位符是部署运行时（vefaas）替换的，
- * 直接交给 html-minifier-terser 会被解析破坏。先把它们抽出来用 `__HBS_<i>__`
- * 占位，压缩完再放回去。
- */
-declare function minifyHtmlWithHbsProtection(html: string): Promise<string>;
-/**
- * 仅 build 期生效的 HTML 压缩插件。
- *
- * dev 期完全 no-op（不挂 hook、不读盘）；
- * build 完毕时（closeBundle）读 `outDir/index.html` 压缩后写回。
- */
-declare function htmlMinifyPlugin(): Plugin;
-
-interface StaticAssetsPluginOptions {
-    /** Client base path prefix for routes. */
-    clientBasePath?: string;
-    /** Project root directory. Defaults to `process.cwd()`. */
-    rootDir?: string;
-}
-declare function staticAssetsPlugin(options?: StaticAssetsPluginOptions): Plugin;
-
-interface CapabilitiesBundlePluginOptions {
-    /** 覆盖扫描目录（相对项目根）。不传时按默认目录列表依次扫描。 */
-    dir?: string;
-}
-/**
- * 把业务工程 `<dir>/*.json` 的 capability 配置打成 `virtual:capabilities` 虚拟模块。
- *
- * `@lark-apaas/client-capability` SDK（被 client-toolkit-lite 内联使用）会
- * `import map from 'virtual:capabilities'` 取这个 map。SDK 在 dev 预览 / 沙箱
- * 加载流程中依赖这个模块存在，所以即使 capabilities 目录为空，也必须把模块
- * 注册成解析成功（空 map），否则 rolldown 在 build 时直接 fail。
- *
- * 同时通过 `optimizeDeps.esbuildOptions.plugins` 在 depOptimizer 那条路径上
- * 也提供解析——因为 client-toolkit-lite 是 pre-bundle 进来的，pre-bundle 的
- * esbuild 不会经过 Vite 主 pipeline 的 plugin 链。
- *
- * V1 限制：dev 期更改 capability JSON 后，pre-bundle 产物里的 map 是启动时快照，
- * 不会自动刷新；新增 / 修改 capability 后需要重启 dev server。
- */
-declare function capabilitiesBundlePlugin(options?: CapabilitiesBundlePluginOptions): Plugin;
-
-interface ErrorOverlayPluginOptions {
-    /** Whether to enable the error overlay. Default true. */
-    enabled?: boolean;
-    /** Client base path prefix. Default ''. */
-    clientBasePath?: string;
-}
-/**
- * 自定义 HMR error overlay。
- *
- * - 关掉 Vite 原生 overlay（`server.hmr.overlay = false`）
- * - dev middleware 暴露 `/@error-overlay.js`（按 clientBasePath 加前缀）
- * - HTML head 注入 `<script type="module" src="...">`
- *
- * 只在 dev 期生效；build 时整个 `configureServer` / `transformIndexHtml` 分支不触发。
- */
-declare function errorOverlayPlugin(options?: ErrorOverlayPluginOptions): Plugin;
-
-/**
- * HMR 计时插件（Vite 8+）。
- *
- * 监听文件变更记录起始时间，在 `hotUpdate` 钩子里算出耗时 + 文件数 + 累计大小，
- * 通过 `server.hot.send({ type: 'custom', event: 'hmr-timing' })` 广播给浏览器；
- * 浏览器侧由 inspector / dev panel 收消息展示。
- *
- * dev 期专用；build 完全不挂 hook。
- */
-declare function hmrTimingPlugin(): Plugin;
-
-/**
- * 检测沙箱代理链路下的 WebSocket 僵尸连接。
- *
- * 客户端 5s ping 一次（通过 vite hot.send），连续 2 次拿不到 pong 判死，
- * 向 parent window 发 `postMessage({ type: 'disconnected' })` 通知沙箱外壳。
- *
- * 仅 dev 期生效（`apply: 'serve'`）；本地裸 dev 也开，不会有副作用——
- * parent 不是沙箱时 postMessage 无消费者，自然丢弃。
- */
-interface WsWatchdogPluginOptions {
-    pingEvent?: string;
-    pongEvent?: string;
-    /**
-     * 客户端 base path（如 `/app/app_xxx`）。沙箱网关把完整路径透传给 Vite，
-     * middleware 匹配和注入的 `<script src>` 都必须带 base；空串退化到裸路径。
-     */
-    clientBasePath?: string;
-}
-declare function wsWatchdogPlugin(options?: WsWatchdogPluginOptions): Plugin;
-
-/**
- * 给妙搭沙箱外壳提供统一的 health endpoint。
- *
- * 协议（飞书文档 - 妙搭应用 Health Check 接口规范）：
- *   - HTTP connection refused / timeout → dev server 没起来 → 外壳重启沙箱
- *   - 200 + { ready: true }             → 应用已就绪
- *   - 200 + { ready: false }            → 还在启动，按 error 描述判断重试
- *
- * 不归本接口管：
- *   - vite compile error / runtime error / 资源加载失败 → 浏览器侧自己上报
- */
-interface HealthMiddlewarePluginOptions {
-    /** Health endpoint 路径，默认 `/dev/health`。 */
-    endpoint?: string;
-}
-declare function healthMiddlewarePlugin(options?: HealthMiddlewarePluginOptions): Plugin;
-
-interface ViewContextPluginOptions {
-    /**
-     * 显式传入的 appId override。preset 已经从 `CLIENT_BASE_PATH=/app/<appId>`
-     * 提取，设置后 inline script 直接拼真值字面量。未设置则走 IIFE 从 URL
-     * 解析（prod / 部分本地 dev URL 没 base path 时用）。
-     */
-    appId?: string;
-}
-declare function viewContextPlugin(options?: ViewContextPluginOptions): Plugin;
-
-/**
- * 把业务工程里 `import 'clsx'` / `import 'echarts'` / `import 'echarts-for-react'`
- * 这种裸 import 强制指向 preset 自带的 ESM wrapper（`src/module-alias/*.mjs`）。
- *
- * 解决的问题：第三方扩展（如 `echarts-wordcloud`）自带独立 echarts 副本时，
- * 业务代码和扩展跑在两份 echarts 实例上，wordcloud 注册不到主实例 → 渲染丢失。
- * Wrapper 强制所有 echarts 指针指向 preset 自带版本，全栈共用一份实例。
- */
-declare function moduleAliasPlugin(): Plugin;
-
-/**
- * 向 `index.html` 注入 / 改写 OG meta、title、description meta、favicon。
- *
- * 所有值用 HBS 占位符（`{{appName}}` 等），由部署运行时（vefaas）替换为
- * platform API 拿到的真值；jsPage 流程下浏览器侧不直接消费这些 meta。
- *
- * 既存 tag 会被原地改写（保留其它属性），缺失则插入到 `</head>` 之前。
- */
-interface OgMetaPluginOptions {
-    customTags?: Array<{
-        property: string;
-        placeholder: string;
-    }>;
-    titlePlaceholder?: string;
-    descriptionPlaceholder?: string;
-    faviconPlaceholder?: string;
-}
-declare function ogMetaPlugin(options?: OgMetaPluginOptions): Plugin;
-
-interface FontsMirrorPluginOptions {
-    /** Mirror 完整基址，默认 `https://miaoda.feishu.cn/fonts` */
-    mirror?: string;
-    /** 关闭（调试时兜底） */
-    disabled?: boolean;
-    /** 命中时打 warning（便于找出源码里的旧引用） */
-    warnOnMatch?: boolean;
-    /** 排除 id 子串或正则 */
-    exclude?: (string | RegExp)[];
-}
-declare function fontsMirrorPlugin(options?: FontsMirrorPluginOptions): Plugin | false;
-
-/**
- * 为旧版浏览器生成独立 `polyfills.js`，HTML 注入 detection 脚本按需加载。
- * 现代浏览器不会请求该文件，零开销。
- *
- * 使用 Vite build API 二次 build 把 `src/polyfills/index.ts` 打成 IIFE bundle。
- * 仅生产构建生效（`apply: 'build'`）。
- */
-declare function polyfillPlugin(): Plugin;
-
-declare function viteClientPatchPlugin(): Plugin;
-
-/**
- * 注入 Slardar SDK + Performance + Tea 监控埋点。
- *
- * 三段都通过 `<script>` 注入到 head-prepend：
- *   1. Slardar SDK loader（onload 后读 `window.tenantId/appId/userId/ENVIRONMENT` 初始化）
- *   2. Performance SDK
- *   3. Tea SDK loader
- *
- * 依赖 viewContextPlugin 提前注入 `window.tenantId/appId/userId/ENVIRONMENT`。
- *
- * head-prepend bucket：Vite 同 bucket 是"后执行者插更前"。
- * 数组里 slardar 必须排在 viewContext **之前** —— 这样在 HTML 里 viewContext 出现在
- * slardar 之上，slardar onload 时才能读到 window.tenantId 等真值。
- */
-interface SlardarPluginOptions {
-    /** Business ID。默认 `apaas_miaoda` */
-    bid?: string;
-    /** SDK 暴露在 window 上的全局名。默认 `KSlardarWeb` */
-    globalName?: string;
-}
-declare function slardarPlugin(options?: SlardarPluginOptions): Plugin;
-
-/**
- * 客户端日志收集 + 读取 + SSE 流式 endpoint。
- *
- * 写入：
- *   - `POST <basePath>/dev/logs/collect`        单条 log（`{ message, ... }`）
- *   - `POST <basePath>/dev/logs/collect-batch`  数组批量 log
- *
- * 读取：
- *   - `GET <basePath>/dev/logs/files/:fileName?page=1&pageSize=200`
- *     倒序分页读 `<logDir>/<fileName>` 任意文件，防 path traversal，max pageSize 2000
- *   - `GET <basePath>/dev/logs/server-logs?limit=100&offset=0&levels=error,warn&sources=client-std`
- *     合并 4 个常见日志文件（server.log / trace.log / server.std.log / client.std.log）
- *     的 entries，按 timestamp desc 排序后分页 + 过滤
- *   - `GET <basePath>/dev/logs/server-logs/stream`（SSE）
- *     `LogWatcher` 增量监听 4 个文件，新行实时推送
- *
- * jsPage 说明：endpoint 名字带 "server-" 是历史遗留（与 `client-toolkit` 写死的路径
- * 兼容，见 `client-toolkit/src/server-log/poller.ts`）；实际只监测一个文件
- * `client.std.log`（dev.mjs 写的）。上游另外那 3 个（`server.log`、`trace.log`、
- * `server.std.log`）是 fullstack 后端的产物，jsPage 不产、也没消费者，全部砍掉。
- *
- * 写入路径：`<logDir>/<fileName>`（默认 `./logs/client.log`，由 `LOG_DIR` 环境变量改写）。
- *
- * 移植自上游 `@lark-apaas/devtool-kits` 的 `dev-logs` + `collect-logs` middlewares。
- * 仍然不补的 fullstack-only endpoints：
- *   - `/app/trace/:traceId`、`/trace/recent`、`/trace/trigger/*`、`/trace/capability/list`
- *     —— 全是 server-side trace.log 的索引接口
- *   - `/api-list` —— 从 fullstack server 抓 API route 清单
- *   - `/health` —— 重复（本 preset 有独立 `/dev/health`）
- */
-interface DevLogsPluginOptions {
-    /** 日志写入目录。默认 `process.env.LOG_DIR ?? './logs'`。 */
-    logDir?: string;
-    /** 日志文件名。默认 `client.log`。 */
-    fileName?: string;
-    /** Body 大小上限（bytes）。默认 20 MB。 */
-    bodyLimit?: number;
-    /** 接口基路径前缀（沙箱 base path）。默认空。 */
-    basePath?: string;
-}
-declare function devLogsPlugin(options?: DevLogsPluginOptions): Plugin;
-
-/**
- * 标准化 base path：
- *   - 空 / undefined → 空字符串
- *   - 前面强制加 `/`
- *   - 去掉尾部 `/`
- *
- * 例：
- *   normalizeBasePath('')          === ''
- *   normalizeBasePath('/')         === ''
- *   normalizeBasePath('foo')       === '/foo'
- *   normalizeBasePath('/foo/')     === '/foo'
- *   normalizeBasePath('/app/x/')   === '/app/x'
- */
-declare function normalizeBasePath(input: string | undefined): string;
-
-/**
- * `/dev/snapdom-proxy?url=<encoded>` 转发到目标 URL，带上 request cookie。
- * 给客户端截图（snapdom）库做跨域兜底用。仅 dev。
- */
-interface SnapDomMiddlewareOptions {
-    proxyUrl?: string;
-    baseUrl?: string;
-}
-declare function registerSnapDomProxyMiddleware(middlewares: Connect.Server, options?: SnapDomMiddlewareOptions): void;
-
-/**
- * miaoda-coding vite-react (jsPage) 默认 Vite 配置。
- *
- * 通过环境变量自动读取部署相关参数，用户只需提供项目特有的覆盖：
- *
- * ```ts
- * import { defineConfig } from '@lark-apaas/coding-preset-vite-react';
- * import path from 'node:path';
- *
- * export default defineConfig({
- *   resolve: {
- *     alias: {
- *       '@': path.resolve(__dirname, 'src'),
- *       '@shared': path.resolve(__dirname, 'shared'),
- *     },
- *   },
- * });
- * ```
- *
- * 支持环境变量：
- *   - NODE_ENV            development | production（默认 development）
- *   - CLIENT_BASE_PATH    部署侧 client base path（如 `/app/<id>`）
- *   - ASSETS_CDN_PATH     生产 JS/CSS CDN 前缀（可选）
- *   - CLIENT_DEV_PORT     dev server 端口（默认 8080）
- *   - CLIENT_DEV_HOST     dev server host（默认 localhost）
- *   - FORCE_FRAMEWORK_DOMAIN_MAIN  反向代理域名（启用 wss HMR + 设置 ACAO）
- *   - DISABLE_INSPECTOR   `true` 关 inspector
- *   - MIAODA_FONTS_MIRROR_OFF  `1` 关 Google Fonts 代理替换
- *   - MIAODA_APP_TYPE     妙搭应用类型（数字字符串，供 lite Safety 徽标判断）
- */
-declare function defineConfig(overrides?: UserConfig): UserConfig;
-
-export { capabilitiesBundlePlugin, defineConfig as default, defineConfig, devLogsPlugin, errorOverlayPlugin, fontsMirrorPlugin, healthMiddlewarePlugin, hmrTimingPlugin, htmlMinifyPlugin, minifyHtmlWithHbsProtection, moduleAliasPlugin, normalizeBasePath, ogMetaPlugin, parseRoutes, polyfillPlugin, registerSnapDomProxyMiddleware, routesPlugin, slardarPlugin, staticAssetsPlugin, viewContextPlugin, viteClientPatchPlugin, wsWatchdogPlugin };