@finesoft/front 0.1.13 → 0.1.15

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { FrameworkConfig, Framework, BasePage, PrefetchedIntent } from './browser.cjs';
 export { ACTION_KINDS, Action, ActionDispatcher, ActionHandler, ActionHandlerDependencies, AsyncMapper, BaseController, BaseItem, BaseLogger, BaseShelf, BrowserAppConfig, CompositeLogger, CompositeLoggerFactory, CompoundAction, ConsoleLogger, ConsoleLoggerFactory, Container, DEP_KEYS, ExternalUrlAction, ExternalUrlDependencies, FeatureFlags, FlowAction, FlowActionCallbacks, FlowActionDependencies, History, HttpClient, HttpClientConfig, HttpError, Intent, IntentController, IntentDispatcher, Locale, Logger, LoggerFactory, Logger as LoggerInterface, LruMap, Mapper, MetricsRecorder, Net, None, Optional, PrefetchedIntents, RouteDefinition, RouteMatch, Router, Storage, buildUrl, createPrefetchedIntentsFromDom, defineRoutes, deserializeServerData, generateUuid, getBaseUrl, isCompoundAction, isExternalUrlAction, isFlowAction, isNone, isSome, makeDependencies, makeExternalUrlAction, makeFlowAction, mapEach, pipe, pipeAsync, registerActionHandlers, registerExternalUrlHandler, registerFlowActionHandler, removeHost, removeQueryParams, removeScheme, resetFilterCache, shouldLog, stableStringify, startBrowserApp, tryScroll } from './browser.cjs';
+import * as node_fs from 'node:fs';
 import { Hono } from 'hono';
 import { ViteDevServer } from 'vite';
 
@@ -96,6 +97,160 @@ declare function injectSSRContent(options: InjectSSROptions): string;
 
 declare function serializeServerData(data: PrefetchedIntent[]): string;
 
+/**
+ * Adapter 接口定义
+ *
+ * 每个适配器实现 Adapter 接口，在 vite build 的 closeBundle 阶段
+ * 接收 AdapterContext 并生成目标平台的部署产物。
+ */
+/** 适配器上下文 — 由 vite-plugin 的 closeBundle 构造后传入 adapter.build() */
+interface AdapterContext {
+    /** 项目根路径 */
+    root: string;
+    /** SSR 入口文件相对路径（如 "src/ssr.ts"） */
+    ssrEntry: string;
+    /** setup 文件相对路径（如 "src/proxies.ts"），仅当 options.setup 为 string 时有值 */
+    setupPath?: string;
+    /** 支持的语言列表 */
+    locales: string[];
+    /** 默认语言 */
+    defaultLocale: string;
+    /** dist/client/index.html 的内容 */
+    templateHtml: string;
+    /** Vite 的 resolve 配置 */
+    resolvedResolve: unknown;
+    /** Vite 的 css 配置 */
+    resolvedCss: unknown;
+    vite: any;
+    fs: typeof node_fs;
+    path: {
+        resolve: (...args: string[]) => string;
+        join: (...args: string[]) => string;
+    };
+    /** 生成 serverless/edge function 入口源码 */
+    generateSSREntry(opts: GenerateSSREntryOptions): string;
+    /** 用 Vite SSR 模式构建 bundle */
+    buildBundle(opts: BuildBundleOptions): Promise<void>;
+    /** 复制 dist/client 静态资源到目标目录 */
+    copyStaticAssets(destDir: string, opts?: CopyStaticAssetsOptions): void;
+}
+interface GenerateSSREntryOptions {
+    /** 平台特定的导入语句（如 `import { handle } from "hono/vercel";`） */
+    platformImport: string;
+    /** 平台特定的导出语句（如 `export default handle(app);`） */
+    platformExport: string;
+}
+interface BuildBundleOptions {
+    /** 临时入口文件路径 */
+    entry: string;
+    /** 输出目录 */
+    outDir: string;
+    /** 构建 target（默认 "node18"） */
+    target?: string;
+    /** 输出文件名（默认 "index.mjs"） */
+    fileName?: string;
+    /** 排除的模块（默认 ["vite", "esbuild", "rollup", "fsevents", "lightningcss"]） */
+    external?: string[];
+    /** 是否打包所有依赖（默认 true） */
+    noExternal?: boolean;
+}
+interface CopyStaticAssetsOptions {
+    /** 是否排除 index.html（默认 true） */
+    excludeHtml?: boolean;
+}
+/** 适配器接口 */
+interface Adapter {
+    /** 适配器名称（用于日志） */
+    name: string;
+    /** 生成目标平台部署产物 */
+    build(ctx: AdapterContext): Promise<void>;
+}
+
+/**
+ * Auto 适配器 — 根据环境变量自动选择目标平台
+ *
+ * 检测顺序：
+ *   VERCEL       → vercel
+ *   CF_PAGES     → cloudflare
+ *   NETLIFY      → netlify
+ *   (default)    → node
+ */
+
+declare function autoAdapter(): Adapter;
+
+/**
+ * Cloudflare Pages 适配器
+ *
+ * 生成 dist/cloudflare/ 目录：
+ * - _worker.js — Workers 入口（Hono 原生支持 CF fetch 接口）
+ * - assets/    — 静态资源
+ *
+ * 注意：Cloudflare Workers 不支持原生 Node.js API。
+ * 若 setup 代理使用了 process.env，需在 wrangler.toml 启用 nodejs_compat。
+ */
+
+declare function cloudflareAdapter(): Adapter;
+
+/**
+ * Netlify 适配器 — Netlify Functions v2
+ *
+ * 生成：
+ * - .netlify/functions-internal/ssr/index.mjs — Serverless Function
+ * - dist/client/_redirects — 路由重写规则
+ */
+
+declare function netlifyAdapter(): Adapter;
+
+/**
+ * Node 适配器 — 独立 HTTP 服务器
+ *
+ * 生成 dist/server/index.mjs，使用 @hono/node-server 监听端口。
+ * 运行：node dist/server/index.mjs
+ */
+
+declare function nodeAdapter(): Adapter;
+
+/**
+ * resolveAdapter — 字符串 → Adapter 映射
+ */
+
+declare function resolveAdapter(value: string | Adapter): Adapter;
+
+/**
+ * Static 适配器 — 构建时预渲染
+ *
+ * 加载 SSR 模块和路由定义，将无参数路由自动预渲染为静态 HTML。
+ * 动态参数路由通过 dynamicRoutes 选项补充具体 URL。
+ *
+ * 输出：dist/static/ — 纯静态站点，可部署到任何静态托管。
+ */
+
+interface StaticAdapterOptions {
+    /**
+     * 导出 routes 数组的文件路径（相对于项目根目录）。
+     * 默认 "src/lib/bootstrap.ts"。
+     * 文件需 export 一个 RouteDefinition[] 类型的 routes 变量。
+     */
+    routesExport?: string;
+    /**
+     * 额外的动态路由 URL（带具体参数值），如：
+     * ["/product/123", "/list/games"]
+     */
+    dynamicRoutes?: string[];
+}
+declare function staticAdapter(opts?: StaticAdapterOptions): Adapter;
+
+/**
+ * Vercel 适配器 — Build Output API v3
+ *
+ * 生成 .vercel/output/ 目录：
+ * - config.json — 路由规则
+ * - static/     — 静态资源
+ * - functions/ssr.func/ — Serverless Function
+ */
+
+declare function vercelAdapter(): Adapter;
+
 /**
  * createSSRApp — 创建 Hono SSR 应用
  *
@@ -224,4 +379,50 @@ declare function startServer(options: StartServerOptions): Promise<{
     vite?: ViteDevServer;
 }>;
 
-export { BasePage, Framework, FrameworkConfig, type InjectSSROptions, PrefetchedIntent, type RuntimeInfo, type SSRAppOptions, type SSRModule, type SSRRenderConfig, type SSRRenderOptions, type SSRRenderResult, SSR_PLACEHOLDERS, type ServerConfig, type ServerInstance, type StartServerOptions, createSSRApp, createSSRRender, createServer, detectRuntime, injectSSRContent, parseAcceptLanguage, resolveRoot, serializeServerData, ssrRender, startServer };
+/**
+ * finesoftFrontViteConfig — Vite 插件
+ *
+ * 将 Hono SSR 服务器集成到 Vite 的 dev / build / preview 生命周期中，
+ * 使 template-project 只需 `vite` / `vite build` / `vite preview` 即可运行。
+ *
+ * 支持多平台 adapter: "vercel" | "cloudflare" | "netlify" | "node" | "static" | "auto"
+ * 或自定义 Adapter 对象。
+ */
+
+interface FinesoftFrontViteOptions {
+    /** 支持的语言列表 */
+    locales?: string[];
+    /** 默认语言 */
+    defaultLocale?: string;
+    /** SSR 配置 */
+    ssr?: {
+        /** SSR 入口文件路径（默认 "src/ssr.ts"） */
+        entry?: string;
+    };
+    /**
+     * 注册业务路由（API 代理等）。
+     * - 传入 Function：仅 dev/preview 时可用。
+     * - 传入 string（文件路径）：dev/preview/adapter 均可用，
+     *   文件需 export default 一个 (app: Hono) => void 函数。
+     */
+    setup?: ((app: Hono) => void | Promise<void>) | string;
+    /**
+     * 部署适配器。
+     * - 字符串快捷方式："vercel" | "cloudflare" | "netlify" | "node" | "static" | "auto"
+     * - 自定义 Adapter 对象：{ name, build(ctx) }
+     * - 不设置则不生成部署产物
+     */
+    adapter?: string | Adapter;
+}
+declare function finesoftFrontViteConfig(options?: FinesoftFrontViteOptions): {
+    name: string;
+    config(userConfig: Record<string, any>, env: {
+        command: string;
+    }): Record<string, any>;
+    configResolved(config: Record<string, any>): void;
+    configureServer(server: any): () => Promise<void>;
+    configurePreviewServer(server: any): () => Promise<void>;
+    closeBundle(): Promise<void>;
+};
+
+export { type Adapter, type AdapterContext, BasePage, type FinesoftFrontViteOptions, Framework, FrameworkConfig, type InjectSSROptions, PrefetchedIntent, type RuntimeInfo, type SSRAppOptions, type SSRModule, type SSRRenderConfig, type SSRRenderOptions, type SSRRenderResult, SSR_PLACEHOLDERS, type ServerConfig, type ServerInstance, type StartServerOptions, autoAdapter, cloudflareAdapter, createSSRApp, createSSRRender, createServer, detectRuntime, finesoftFrontViteConfig, injectSSRContent, netlifyAdapter, nodeAdapter, parseAcceptLanguage, resolveAdapter, resolveRoot, serializeServerData, ssrRender, startServer, staticAdapter, vercelAdapter };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { FrameworkConfig, Framework, BasePage, PrefetchedIntent } from './browser.js';
 export { ACTION_KINDS, Action, ActionDispatcher, ActionHandler, ActionHandlerDependencies, AsyncMapper, BaseController, BaseItem, BaseLogger, BaseShelf, BrowserAppConfig, CompositeLogger, CompositeLoggerFactory, CompoundAction, ConsoleLogger, ConsoleLoggerFactory, Container, DEP_KEYS, ExternalUrlAction, ExternalUrlDependencies, FeatureFlags, FlowAction, FlowActionCallbacks, FlowActionDependencies, History, HttpClient, HttpClientConfig, HttpError, Intent, IntentController, IntentDispatcher, Locale, Logger, LoggerFactory, Logger as LoggerInterface, LruMap, Mapper, MetricsRecorder, Net, None, Optional, PrefetchedIntents, RouteDefinition, RouteMatch, Router, Storage, buildUrl, createPrefetchedIntentsFromDom, defineRoutes, deserializeServerData, generateUuid, getBaseUrl, isCompoundAction, isExternalUrlAction, isFlowAction, isNone, isSome, makeDependencies, makeExternalUrlAction, makeFlowAction, mapEach, pipe, pipeAsync, registerActionHandlers, registerExternalUrlHandler, registerFlowActionHandler, removeHost, removeQueryParams, removeScheme, resetFilterCache, shouldLog, stableStringify, startBrowserApp, tryScroll } from './browser.js';
+import * as node_fs from 'node:fs';
 import { Hono } from 'hono';
 import { ViteDevServer } from 'vite';
 
@@ -96,6 +97,160 @@ declare function injectSSRContent(options: InjectSSROptions): string;
 
 declare function serializeServerData(data: PrefetchedIntent[]): string;
 
+/**
+ * Adapter 接口定义
+ *
+ * 每个适配器实现 Adapter 接口，在 vite build 的 closeBundle 阶段
+ * 接收 AdapterContext 并生成目标平台的部署产物。
+ */
+/** 适配器上下文 — 由 vite-plugin 的 closeBundle 构造后传入 adapter.build() */
+interface AdapterContext {
+    /** 项目根路径 */
+    root: string;
+    /** SSR 入口文件相对路径（如 "src/ssr.ts"） */
+    ssrEntry: string;
+    /** setup 文件相对路径（如 "src/proxies.ts"），仅当 options.setup 为 string 时有值 */
+    setupPath?: string;
+    /** 支持的语言列表 */
+    locales: string[];
+    /** 默认语言 */
+    defaultLocale: string;
+    /** dist/client/index.html 的内容 */
+    templateHtml: string;
+    /** Vite 的 resolve 配置 */
+    resolvedResolve: unknown;
+    /** Vite 的 css 配置 */
+    resolvedCss: unknown;
+    vite: any;
+    fs: typeof node_fs;
+    path: {
+        resolve: (...args: string[]) => string;
+        join: (...args: string[]) => string;
+    };
+    /** 生成 serverless/edge function 入口源码 */
+    generateSSREntry(opts: GenerateSSREntryOptions): string;
+    /** 用 Vite SSR 模式构建 bundle */
+    buildBundle(opts: BuildBundleOptions): Promise<void>;
+    /** 复制 dist/client 静态资源到目标目录 */
+    copyStaticAssets(destDir: string, opts?: CopyStaticAssetsOptions): void;
+}
+interface GenerateSSREntryOptions {
+    /** 平台特定的导入语句（如 `import { handle } from "hono/vercel";`） */
+    platformImport: string;
+    /** 平台特定的导出语句（如 `export default handle(app);`） */
+    platformExport: string;
+}
+interface BuildBundleOptions {
+    /** 临时入口文件路径 */
+    entry: string;
+    /** 输出目录 */
+    outDir: string;
+    /** 构建 target（默认 "node18"） */
+    target?: string;
+    /** 输出文件名（默认 "index.mjs"） */
+    fileName?: string;
+    /** 排除的模块（默认 ["vite", "esbuild", "rollup", "fsevents", "lightningcss"]） */
+    external?: string[];
+    /** 是否打包所有依赖（默认 true） */
+    noExternal?: boolean;
+}
+interface CopyStaticAssetsOptions {
+    /** 是否排除 index.html（默认 true） */
+    excludeHtml?: boolean;
+}
+/** 适配器接口 */
+interface Adapter {
+    /** 适配器名称（用于日志） */
+    name: string;
+    /** 生成目标平台部署产物 */
+    build(ctx: AdapterContext): Promise<void>;
+}
+
+/**
+ * Auto 适配器 — 根据环境变量自动选择目标平台
+ *
+ * 检测顺序：
+ *   VERCEL       → vercel
+ *   CF_PAGES     → cloudflare
+ *   NETLIFY      → netlify
+ *   (default)    → node
+ */
+
+declare function autoAdapter(): Adapter;
+
+/**
+ * Cloudflare Pages 适配器
+ *
+ * 生成 dist/cloudflare/ 目录：
+ * - _worker.js — Workers 入口（Hono 原生支持 CF fetch 接口）
+ * - assets/    — 静态资源
+ *
+ * 注意：Cloudflare Workers 不支持原生 Node.js API。
+ * 若 setup 代理使用了 process.env，需在 wrangler.toml 启用 nodejs_compat。
+ */
+
+declare function cloudflareAdapter(): Adapter;
+
+/**
+ * Netlify 适配器 — Netlify Functions v2
+ *
+ * 生成：
+ * - .netlify/functions-internal/ssr/index.mjs — Serverless Function
+ * - dist/client/_redirects — 路由重写规则
+ */
+
+declare function netlifyAdapter(): Adapter;
+
+/**
+ * Node 适配器 — 独立 HTTP 服务器
+ *
+ * 生成 dist/server/index.mjs，使用 @hono/node-server 监听端口。
+ * 运行：node dist/server/index.mjs
+ */
+
+declare function nodeAdapter(): Adapter;
+
+/**
+ * resolveAdapter — 字符串 → Adapter 映射
+ */
+
+declare function resolveAdapter(value: string | Adapter): Adapter;
+
+/**
+ * Static 适配器 — 构建时预渲染
+ *
+ * 加载 SSR 模块和路由定义，将无参数路由自动预渲染为静态 HTML。
+ * 动态参数路由通过 dynamicRoutes 选项补充具体 URL。
+ *
+ * 输出：dist/static/ — 纯静态站点，可部署到任何静态托管。
+ */
+
+interface StaticAdapterOptions {
+    /**
+     * 导出 routes 数组的文件路径（相对于项目根目录）。
+     * 默认 "src/lib/bootstrap.ts"。
+     * 文件需 export 一个 RouteDefinition[] 类型的 routes 变量。
+     */
+    routesExport?: string;
+    /**
+     * 额外的动态路由 URL（带具体参数值），如：
+     * ["/product/123", "/list/games"]
+     */
+    dynamicRoutes?: string[];
+}
+declare function staticAdapter(opts?: StaticAdapterOptions): Adapter;
+
+/**
+ * Vercel 适配器 — Build Output API v3
+ *
+ * 生成 .vercel/output/ 目录：
+ * - config.json — 路由规则
+ * - static/     — 静态资源
+ * - functions/ssr.func/ — Serverless Function
+ */
+
+declare function vercelAdapter(): Adapter;
+
 /**
  * createSSRApp — 创建 Hono SSR 应用
  *
@@ -224,4 +379,50 @@ declare function startServer(options: StartServerOptions): Promise<{
     vite?: ViteDevServer;
 }>;
 
-export { BasePage, Framework, FrameworkConfig, type InjectSSROptions, PrefetchedIntent, type RuntimeInfo, type SSRAppOptions, type SSRModule, type SSRRenderConfig, type SSRRenderOptions, type SSRRenderResult, SSR_PLACEHOLDERS, type ServerConfig, type ServerInstance, type StartServerOptions, createSSRApp, createSSRRender, createServer, detectRuntime, injectSSRContent, parseAcceptLanguage, resolveRoot, serializeServerData, ssrRender, startServer };
+/**
+ * finesoftFrontViteConfig — Vite 插件
+ *
+ * 将 Hono SSR 服务器集成到 Vite 的 dev / build / preview 生命周期中，
+ * 使 template-project 只需 `vite` / `vite build` / `vite preview` 即可运行。
+ *
+ * 支持多平台 adapter: "vercel" | "cloudflare" | "netlify" | "node" | "static" | "auto"
+ * 或自定义 Adapter 对象。
+ */
+
+interface FinesoftFrontViteOptions {
+    /** 支持的语言列表 */
+    locales?: string[];
+    /** 默认语言 */
+    defaultLocale?: string;
+    /** SSR 配置 */
+    ssr?: {
+        /** SSR 入口文件路径（默认 "src/ssr.ts"） */
+        entry?: string;
+    };
+    /**
+     * 注册业务路由（API 代理等）。
+     * - 传入 Function：仅 dev/preview 时可用。
+     * - 传入 string（文件路径）：dev/preview/adapter 均可用，
+     *   文件需 export default 一个 (app: Hono) => void 函数。
+     */
+    setup?: ((app: Hono) => void | Promise<void>) | string;
+    /**
+     * 部署适配器。
+     * - 字符串快捷方式："vercel" | "cloudflare" | "netlify" | "node" | "static" | "auto"
+     * - 自定义 Adapter 对象：{ name, build(ctx) }
+     * - 不设置则不生成部署产物
+     */
+    adapter?: string | Adapter;
+}
+declare function finesoftFrontViteConfig(options?: FinesoftFrontViteOptions): {
+    name: string;
+    config(userConfig: Record<string, any>, env: {
+        command: string;
+    }): Record<string, any>;
+    configResolved(config: Record<string, any>): void;
+    configureServer(server: any): () => Promise<void>;
+    configurePreviewServer(server: any): () => Promise<void>;
+    closeBundle(): Promise<void>;
+};
+
+export { type Adapter, type AdapterContext, BasePage, type FinesoftFrontViteOptions, Framework, FrameworkConfig, type InjectSSROptions, PrefetchedIntent, type RuntimeInfo, type SSRAppOptions, type SSRModule, type SSRRenderConfig, type SSRRenderOptions, type SSRRenderResult, SSR_PLACEHOLDERS, type ServerConfig, type ServerInstance, type StartServerOptions, autoAdapter, cloudflareAdapter, createSSRApp, createSSRRender, createServer, detectRuntime, finesoftFrontViteConfig, injectSSRContent, netlifyAdapter, nodeAdapter, parseAcceptLanguage, resolveAdapter, resolveRoot, serializeServerData, ssrRender, startServer, staticAdapter, vercelAdapter };