@hazejs/vite 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present hazejs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @hazejs/vite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Vite plugin for hazejs: hot-reloading backend, full-stack dev server, deployment presets and preview.
+
+## Install
+
+```bash
+pnpm add -D @hazejs/vite
+```
+
+## Usage
+
+```ts
+// vite.config.ts
+import { haze } from '@hazejs/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    haze()
+  ]
+})
+```
+
+In dev, requests to your backend routes are served by the app in `server/` (configurable in `haze.config.ts`); `vite build` emits `dist/client` + `dist/server`; `vite preview` runs the real build output for the selected preset.
+
+Part of [hazejs](https://github.com/penna-org/haze) — see the main README for documentation.
+
+## License
+
+[MIT](./LICENSE)

package/client.d.ts

@@ -0,0 +1,13 @@
+// 虚拟模块类型声明：在 tsconfig 的 types 中加入 "@hazejs/vite/client"
+
+declare module 'virtual:haze/app' {
+  import type { Application, ApplicationOptions } from '@hazejs/core'
+
+  /** 使用编译期发现的 config / route / provider / exception 创建应用 */
+  export function createApp(options?: ApplicationOptions): Promise<Application>
+}
+
+declare module 'virtual:haze/migrations' {
+  /** 打包进产物的迁移文件（相对后端源码目录的路径 → 内容），用于 runMigrations({ files }) */
+  export const files: Record<string, string>
+}

package/dist/index.d.mts

@@ -0,0 +1,373 @@
+import { Plugin, PreviewServer, UserConfig, ViteDevServer } from "vite";
+import { Application, RouteInfo } from "@hazejs/core";
+/** 依赖处理选项（haze.config.ts 的 externals） */
+interface ExternalsOptions {
+  /**
+   * 构建后把仍为 external 的依赖按实际引用的文件追踪复制到产物的 node_modules（node / bun / deno），默认 true。
+   * false 时 node / bun 不打包依赖，运行时从项目的 node_modules 加载。aws-lambda / vercel 始终追踪。
+   */
+  trace?: boolean;
+  /**
+   * 保持 external 并追踪进产物的包（默认已包含数据库驱动与已知的原生 / 无法打包的包）。
+   * `pkg*` 表示整包复制（运行时动态读取文件、静态分析不到时）。
+   */
+  traceDeps?: string[];
+  /** 强制打包进产物的包（覆盖默认的 external 列表） */
+  inline?: string[];
+}
+interface TraceResult {
+  /** 复制进产物的包（含传递依赖） */
+  packages: string[];
+  /** 构建机与目标平台不一致的原生包 */
+  foreignNative: string[];
+}
+export declare const PRESET_NAMES: readonly ["node", "bun", "deno", "docker", "cloudflare", "vercel", "netlify", "aws-lambda"];
+type PresetName = (typeof PRESET_NAMES)[number];
+/** haze.config.ts 的 cloudflare 选项 */
+interface CloudflareOptions {
+  /**
+   * 合并进生成的 wrangler.json（D1 / KV / R2 绑定、vars、routes 等）。
+   * `d1_databases` 中未设置 `migrations_dir` 的数据库使用产物中的 `migrations`（默认连接的迁移）。
+   */
+  wrangler?: Record<string, unknown>;
+  /** 生成 WebSocket 的 Durable Object（默认在路由中发现 r.ws() 时生成） */
+  websocket?: boolean;
+}
+/** haze.config.ts 的 vercel 选项 */
+interface VercelOptions {
+  /** 定时任务的触发频率（Vercel Cron 表达式），默认每分钟；Hobby 计划只允许每天一次 */
+  cron?: string;
+}
+interface PresetContext {
+  root: string;
+  /** haze.config.ts 的 externals 选项 */
+  externalsOptions: ExternalsOptions;
+  /** 后端源码目录（绝对路径） */
+  srcDir: string;
+  /** haze.config.ts 的 outDir（绝对路径） */
+  outDir: string;
+  /** 是否包含前端（Vue 等）构建 */
+  fullstack: boolean;
+  /** 交给后端处理的路径前缀（全栈模式） */
+  prefixes: string[];
+  port: number;
+  host: string | undefined;
+  /** 项目使用 @hazejs/orm：生成生产迁移入口 */
+  orm: boolean;
+  cloudflare: CloudflareOptions | undefined;
+  vercel: VercelOptions | undefined;
+  /** 存在 schedule/*.ts：生成 Cron Triggers / Vercel Cron 等触发配置 */
+  schedules: boolean;
+  /** 路由中使用了 r.ws()：Cloudflare 生成 WebSocket 的 Durable Object */
+  websocket: boolean;
+}
+interface Layout {
+  /** 服务端产物目录 */
+  serverDir: string;
+  /** 前端产物目录（全栈模式） */
+  clientDir: string | undefined;
+  /**
+   * 运行时托管前端产物的目录（相对服务端入口）；
+   * undefined 表示静态资源由平台（CDN）提供
+   */
+  staticFromServer: string | undefined;
+}
+interface FinalizeContext extends PresetContext {
+  layout: Layout;
+  /** 服务端产物中仍需从 node_modules 加载的依赖 */
+  externals: string[];
+  /** 追踪复制进产物的依赖（未追踪时为 undefined） */
+  traced: TraceResult | undefined;
+}
+interface Preset {
+  name: PresetName;
+  /**
+   * - external：依赖保留在 node_modules
+   * - drivers-external：除数据库驱动（原生二进制 / WASM）外全部打包，驱动运行时安装或随产物复制
+   * - all：全部打包（Edge 运行时没有 node_modules，驱动按 workerd 等条件使用其 Web 版本）
+   */
+  bundle: 'external' | 'drivers-external' | 'all';
+  /**
+   * 构建后把 external 依赖追踪复制进 `<serverDir>/node_modules`：
+   * - default：默认开启，`externals.trace: false` 时关闭（node / bun 改为依赖全部 external）
+   * - always：产物必须自带依赖（Serverless 函数）
+   */
+  trace?: 'default' | 'always';
+  /** 产物的运行平台（与构建机不同时检查追踪到的原生包） */
+  runtimePlatform?: NodeJS.Platform;
+  /** 构建时的 package.json exports 条件 */
+  conditions?: string[];
+  target?: string;
+  /** 打包平台：Edge 运行时使用 browser，避免生成依赖 import.meta.url 的 createRequire 辅助代码 */
+  platform?: 'node' | 'browser' | 'neutral';
+  /** 解析 package.json 的入口字段（含 browser 时同时应用 browser 字段的文件映射） */
+  mainFields?: string[];
+  /** 替换为“调用即报错”空模块的包（该运行时不支持） */
+  unsupported?: string[];
+  /** 输出单文件（Workers 要求入口模块只导出处理器，不能被拆分出的 chunk 反向导入） */
+  singleFile?: boolean;
+  /** 保留为运行时导入的模块（如 Workers 的 `cloudflare:*`） */
+  external?: RegExp[];
+  /** 输出独立的迁移脚本 `migrate.mjs`（常驻进程型运行时，部署前执行） */
+  migrateScript?: boolean;
+  layout: (context: PresetContext) => Layout;
+  /** 生产入口（virtual:haze/server-entry）源码 */
+  entry: (context: PresetContext & {
+    layout: Layout;
+  }) => string;
+  /** 构建完成后生成平台配置、复制依赖等 */
+  finalize?: (context: FinalizeContext) => Promise<void>;
+  /** 构建完成后提示如何运行 / 部署 */
+  hint: (context: FinalizeContext) => string;
+}
+export declare const presets: Record<PresetName, Preset>;
+export declare function resolvePreset(name: string | undefined): Preset;
+interface HazePluginOptions {
+  /** 后端源码目录，相对 Vite root 或绝对路径；默认读取 haze.config.ts，否则为 `.` */
+  srcDir?: string;
+  /** 交给后端处理的路径前缀（全栈模式），默认 `/api` */
+  prefix?: string | string[];
+  /** 指向 srcDir 的路径别名，默认 `~`；设为 false 关闭 */
+  alias?: string | false;
+  /** 生产入口的默认端口 / 地址（运行时 PORT / HOST 环境变量优先） */
+  port?: number;
+  host?: string;
+  /** 开发时自动生成类型（默认读取 haze.config.ts，否则为 true） */
+  typegen?: boolean;
+  /** 部署预设，默认读取 HAZE_PRESET 环境变量 / haze.config.ts，否则为 node */
+  preset?: PresetName;
+  /** 产物目录（默认读取 haze.config.ts） */
+  outDir?: string;
+  /** cloudflare 预设的 wrangler 配置（默认读取 haze.config.ts） */
+  cloudflare?: CloudflareOptions;
+  /** vercel 预设的选项（默认读取 haze.config.ts） */
+  vercel?: VercelOptions;
+  /** 依赖的打包 / 追踪方式（默认读取 haze.config.ts） */
+  externals?: ExternalsOptions;
+  /**
+   * 不集成 Vite 开发服务器与前端构建（不挂载中间件、不配置 client / ssr 构建）。
+   * 由 `haze dev / build` 与 `@hazejs/testing` 使用。
+   */
+  standalone?: boolean;
+}
+interface ReloadEvent {
+  type: 'create' | 'update' | 'delete';
+  file: string;
+}
+interface HazePluginApi {
+  /** 后端相关文件变化时通知（开发服务器据此热替换应用） */
+  onReload: (listener: (event: ReloadEvent) => void) => () => void;
+  /** 解析后的目录与选项（config 钩子执行之后可用） */
+  settings: () => Readonly<Pick<Settings, 'root' | 'srcDir' | 'typegen' | 'preset'>>;
+  /** 最近一次构建的结果（buildApp 完成后可用） */
+  lastBuild: () => BuildInfo | undefined;
+}
+interface BuildInfo {
+  preset: PresetName;
+  layout: Layout;
+  /** 运行时仍需从 node_modules 加载的依赖 */
+  externals: string[];
+  /** 追踪复制进产物 node_modules 的依赖 */
+  traced: TraceResult | undefined;
+  /** 服务端入口 */
+  entry: string;
+  /** 生产迁移脚本（使用 @hazejs/orm 且为常驻进程型预设时） */
+  migrate?: string;
+  /** 运行 / 部署提示 */
+  hint: string;
+}
+interface Settings {
+  root: string;
+  srcDir: string;
+  outDir: string;
+  typegen: boolean;
+  port: number;
+  host: string | undefined;
+  prefixes: string[];
+  fullstack: boolean;
+  preset: string;
+  orm: boolean;
+  cloudflare: CloudflareOptions | undefined;
+  vercel: VercelOptions | undefined;
+  externals: ExternalsOptions;
+}
+/**
+ * hazejs 的 Vite 插件。
+ *
+ * - 纯后端项目：由 `hazejs` 命令行内部使用
+ * - Vue 等前端项目：在 vite.config.ts 中加入 `haze()`，开发时把 `/api/**` 交给后端（同端口、热替换），
+ *   `vite build` 一次产出 `dist/client` 与 `dist/server`
+ */
+export declare function haze(options?: HazePluginOptions): Plugin<HazePluginApi>;
+interface BuildServerOptions {
+  root?: string;
+  /** 覆盖 haze.config.ts 中的 outDir */
+  outDir?: string;
+  /** 部署预设，默认读取 haze.config.ts，否则为 node */
+  preset?: PresetName;
+  minify?: boolean;
+  sourcemap?: boolean;
+}
+interface BuildServerResult extends BuildInfo {
+  outDir: string;
+}
+/**
+ * 构建纯后端项目的生产产物。产物布局、打包策略与入口由部署预设决定；
+ * node 预设下依赖保持 external（运行时需要 node_modules），`.env` 从运行时工作目录加载。
+ */
+export declare function buildServer(options?: BuildServerOptions): Promise<BuildServerResult>;
+interface HazeConfig {
+  /** 后端源码目录（相对项目根），默认 `.`；全栈项目一般为 `server` */
+  srcDir?: string;
+  /** 开发服务器端口，默认 3000（环境变量 PORT 优先） */
+  port?: number;
+  /** 监听地址，默认 localhost */
+  host?: string;
+  /** 构建输出目录，默认 `dist` */
+  outDir?: string;
+  /** 开发时自动生成配置键 / 路由名类型到 .haze/types，默认 true */
+  typegen?: boolean;
+  /** 部署预设：node（默认）| bun | deno | docker | cloudflare | vercel | netlify | aws-lambda */
+  preset?: PresetName;
+  /** cloudflare 预设：合并进 wrangler.json 的绑定等配置 */
+  cloudflare?: CloudflareOptions;
+  /** vercel 预设：定时任务触发频率等 */
+  vercel?: VercelOptions;
+  /** 依赖处理：默认能打包的都打包，驱动 / 原生模块追踪复制进产物的 node_modules */
+  externals?: ExternalsOptions;
+  /** 透传给 Vite 的配置（插件、别名等） */
+  vite?: UserConfig;
+}
+interface ResolvedHazeConfig {
+  root: string;
+  srcDir: string;
+  port: number;
+  host: string | undefined;
+  outDir: string;
+  typegen: boolean;
+  preset: PresetName | undefined;
+  cloudflare: CloudflareOptions | undefined;
+  vercel: VercelOptions | undefined;
+  externals: ExternalsOptions | undefined;
+  vite: UserConfig;
+  configFile: string | undefined;
+}
+export declare function defineHazeConfig(config: HazeConfig): HazeConfig;
+/** 存在 vite.config.* 视为全栈项目：由用户的 Vite 配置（含 haze() 插件）驱动 */
+export declare function findViteConfig(root: string): string | undefined;
+/** 读取项目根目录下的 `haze.config.ts`（可选） */
+export declare function loadHazeConfig(root: string, mode?: string): Promise<ResolvedHazeConfig>;
+export declare const CONFIG_BASENAME = "haze.config";
+export declare const VIRTUAL_MODULES: {
+  /** 编译期发现的配置 / 路由 / 提供者 / 异常处理器 */
+  readonly manifest: "virtual:haze/manifest";
+  /** `createApp(options)`：用 manifest 创建应用 */
+  readonly app: "virtual:haze/app";
+  /** 生产环境入口：创建应用并监听端口 */
+  readonly serverEntry: "virtual:haze/server-entry";
+  /** 打包进产物的迁移文件（database/ 下的 drizzle-kit 输出） */
+  readonly migrations: "virtual:haze/migrations";
+  /** 生产迁移脚本入口（migrate.mjs） */
+  readonly migrateEntry: "virtual:haze/migrate-entry";
+  /** 队列 worker 与定时任务入口（worker.mjs） */
+  readonly workerEntry: "virtual:haze/worker-entry";
+};
+interface ReloadResult {
+  ok: boolean;
+  /** 触发重载的文件（相对项目根），首次启动为 undefined */
+  file?: string;
+  duration: number;
+  error?: unknown;
+}
+interface AppHostOptions {
+  vite: ViteDevServer;
+  api: HazePluginApi;
+  /** 文件变化后的防抖时间，默认 30ms */
+  debounce?: number;
+}
+/**
+ * 托管开发态应用：通过 Vite ModuleRunner 执行应用代码，文件变化时重新执行并原子替换。
+ * 独立开发服务器（srvx）与 Vue 项目中的 Vite 中间件共用它。
+ */
+interface AppHost {
+  /** 当前正在服务的应用 */
+  readonly app: Application | undefined;
+  /** 首次加载应用（幂等）；未调用时首个请求会自动触发 */
+  start: () => Promise<ReloadResult>;
+  fetch: (request: Request) => Promise<Response>;
+  /** 手动触发一次重载 */
+  reload: (file?: string) => Promise<ReloadResult>;
+  onReload: (listener: (result: ReloadResult) => void) => () => void;
+  /** 在应用的模块图中执行模块（与应用共享同一份依赖实例，例如数据库连接） */
+  import: <T = any>(id: string) => Promise<T>;
+  close: () => Promise<void>;
+}
+export declare function createAppHost({ vite, api, debounce }: AppHostOptions): AppHost;
+interface DevServerOptions {
+  /** 项目根目录，默认 `process.cwd()` */
+  root?: string;
+  port?: number;
+  host?: string;
+  /** false 时不监听端口，只通过 `devServer.fetch()` 访问（测试 / 嵌入） */
+  listen?: boolean;
+  /** 文件变化后的防抖时间，默认 30ms */
+  debounce?: number;
+}
+interface DevServer {
+  readonly url: string | undefined;
+  readonly vite: ViteDevServer;
+  /** 当前正在服务的应用 */
+  readonly app: Application | undefined;
+  fetch: (request: Request) => Promise<Response>;
+  /** 手动触发一次重载 */
+  reload: (file?: string) => Promise<ReloadResult>;
+  onReload: (listener: (result: ReloadResult) => void) => () => void;
+  /** 在应用的模块图中执行模块（命令行的 db:migrate / db:seed 使用） */
+  import: <T = any>(id: string) => Promise<T>;
+  close: () => Promise<void>;
+}
+/**
+ * 纯后端项目的开发服务器：HTTP 监听只创建一次，文件变化时通过 Vite ModuleRunner
+ * 重新执行应用代码并原子替换 fetch 处理器——进程不重启、端口不断开。
+ */
+export declare function createDevServer(options?: DevServerOptions): Promise<DevServer>;
+/** 构建结果记录（`.haze/build.json`），供 `vite preview` / `haze preview` 使用 */
+interface BuildManifest extends Pick<BuildInfo, 'preset' | 'layout' | 'entry'> {
+  fullstack: boolean;
+  prefixes: string[];
+}
+export declare function readBuildManifest(root: string): BuildManifest;
+interface PreviewServerOptions {
+  /** 项目根目录，默认 `process.cwd()` */
+  root?: string;
+  /** 默认 4173（与 vite preview 一致） */
+  port?: number;
+  host?: string | boolean;
+  open?: boolean;
+}
+/**
+ * 本地预览构建产物（`haze preview`）：按构建时的部署预设运行产物本身。
+ * 全栈项目使用项目的 vite.config.ts（等同 `vite preview`），纯后端项目使用内置配置。
+ */
+export declare function previewServer(options?: PreviewServerOptions): Promise<PreviewServer>;
+interface TypegenOptions {
+  root: string;
+  srcDir: string;
+  routes: readonly RouteInfo[];
+}
+interface TypegenResult {
+  file: string;
+  changed: boolean;
+  configs: string[];
+  routes: string[];
+  policies: string[];
+}
+/** 生成文件位置（需在 tsconfig 的 include 中加入 `.haze/types/**\/*.d.ts`） */
+export declare function typesFile(root: string): string;
+/** 生成配置键与命名路由的类型声明（模块扩充 @hazejs/core） */
+export declare function generateTypes({ root, srcDir, routes }: TypegenOptions): Omit<TypegenResult, 'changed'> & {
+  content: string;
+};
+/** 内容变化时才写入，避免触发编辑器与文件监听的无谓刷新 */
+export declare function writeTypes(options: TypegenOptions): Promise<TypegenResult>;
+export type { AppHost, AppHostOptions, BuildInfo, BuildManifest, BuildServerOptions, BuildServerResult, CloudflareOptions, DevServer, DevServerOptions, ExternalsOptions, HazeConfig, HazePluginApi, HazePluginOptions, Layout, Preset, PresetName, PreviewServerOptions, ReloadEvent, ReloadResult, ResolvedHazeConfig, TraceResult, TypegenOptions, TypegenResult, VercelOptions };