@ruan-cat/vercel-deploy-tool 0.12.2 → 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,247 @@
+import { Command } from 'commander';
+
+/**
+ * @description
+ * 从 drizzle-kit 学的类型验证技巧
+ */
+type Verify<T, U extends T> = U;
+/** 部署目标类型 */
+type DeployTargetType = "static" | "userCommands";
+/** 基础配置 */
+interface DeployTargetBase {
+    /** 部署目标分类 */
+    type: DeployTargetType;
+    /** 目标的工作目录 */
+    targetCWD: `./${string}`;
+    /** 生产环境的访问url */
+    url: string[];
+    /**
+     * 是否需要vercel的build命令？
+     * @description
+     * 某些情况下用户已经能够准备好vercel的目录结构，不需要依赖于 `vercel build` 命令完成目录构建
+     *
+     * 故设计此配置允许用户直接跳过 `vercel build` 命令
+     * @default true
+     */
+    isNeedVercelBuild?: boolean;
+}
+/**
+ * 带有用户命令的配置
+ */
+interface DeployTargetWithUserCommands extends DeployTargetBase {
+    type: Verify<DeployTargetType, "userCommands">;
+    /**
+     * 用户命令
+     * @description
+     * 实际部署的构建命令，通常是真实参与部署的命令
+     *
+     * @example ["pnpm -C=./packages/docs-01-star build:docs"]
+     * @example ["pnpm -C=./packages/monorepo-5 build:docs"]
+     */
+    userCommands: string[];
+    /**
+     * 部署输出路径
+     *
+     * @version 2
+     * @description
+     * 填写打包目录的路径即可。不包含glob语法。
+     * @example "docs/.vitepress/dist"
+     * @example "src/.vuepress/dist"
+     */
+    outputDirectory: string;
+    /**
+     * 是否移动打包目录至特定的vercel部署目录？
+     * @description
+     * 执行完用户命令后，一般会执行文件移动命令，以便于部署
+     *
+     * 该配置用于控制是否执行文件移动命令
+     *
+     * @default true
+     */
+    isCopyDist?: boolean;
+}
+/** 部署目标的具体项目配置 */
+type DeployTarget = DeployTargetBase | DeployTargetWithUserCommands;
+/** Vercel部署工具的配置 */
+interface VercelDeployConfig {
+    /** 项目名称 */
+    vercelProjectName: string;
+    /** 用户token */
+    vercelToken: string;
+    /** 用户组织id */
+    vercelOrgId: string;
+    /** 用户项目id */
+    vercelProjectId: string;
+    /**
+     * 用户提供的 vercel.json 配置文件
+     * @description
+     * 有时候用户需要提供自己的一套配置文件
+     *
+     * 这里提供配置路径
+     */
+    vercelJsonPath?: string;
+    /** 在build命令阶段后执行的用户命令 */
+    afterBuildTasks?: string[];
+    /**
+     * 部署目标
+     * @description
+     * 考虑到可能要部署一揽子的项目，所以这里使用数组
+     *
+     * 考虑monorepo的情况
+     */
+    deployTargets: DeployTarget[];
+}
+
+/**
+ * 定义配置的辅助函数
+ * @description
+ * 提供类型提示和智能补全
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from "@ruan-cat/vercel-deploy-tool";
+ *
+ * export default defineConfig({
+ *   vercelProjectName: "my-project",
+ *   // ...
+ * });
+ * ```
+ */
+declare function defineConfig(config: VercelDeployConfig): VercelDeployConfig;
+
+/**
+ * 异步加载配置（工厂函数模式）
+ * @description
+ * 从约定俗成的配置处，获得用户配置文件。不会在模块导入时自动执行，避免 top-level await 引起的执行时警告。
+ *
+ * 环境变量优先级：
+ * 1) 命令行传入的 env-path（通过 VERCEL_DEPLOY_TOOL_ENV_PATH 或 deploy 命令参数注入）
+ * 2) Node 进程已有的 process.env
+ * 3) c12 默认加载的 .env* 文件
+ *
+ * @example
+ * ```ts
+ * const config = await loadConfig();
+ * ```
+ */
+declare function loadConfig(): Promise<VercelDeployConfig>;
+/**
+ * 导出配置获取函数（带缓存）
+ * @description
+ * 首次调用会触发加载，后续复用结果。避免 top-level await。
+ *
+ * @example
+ * ```ts
+ * import { getConfig } from "@ruan-cat/vercel-deploy-tool";
+ * const config = await getConfig();
+ * ```
+ */
+declare function getConfig(): Promise<VercelDeployConfig>;
+
+/**
+ * 执行 Vercel 部署工作流
+ * @description
+ * 这是整个部署流程的总入口，使用 tasuku 编排所有任务
+ *
+ * 任务执行顺序：
+ * 1. Link 阶段（并行）
+ * 2. Build 阶段（并行）
+ * 3. AfterBuild 阶段（串行）
+ * 4. UserCommands + CopyDist 阶段（并行目标，串行步骤）
+ * 5. Deploy + Alias 阶段（并行目标，串行步骤）
+ */
+declare function executeDeploymentWorkflow(config: VercelDeployConfig): Promise<void>;
+
+/**
+ * Vercel 的空配置
+ * @description
+ * 设计理由：
+ *
+ * 用于驱动vercel构建简单的目录结构，不需要额外的配置
+ *
+ * 该配置会被写入到 `vercel.null.def.json` 文件中
+ *
+ * @see https://github.com/amondnet/vercel-action#method-1---via-vercel-interface
+ */
+declare const VERCEL_NULL_CONFIG: {
+    readonly framework: null;
+    readonly buildCommand: null;
+    readonly installCommand: null;
+    readonly outputDirectory: null;
+    readonly devCommand: null;
+    readonly public: false;
+    /**
+     * 部署后提供干净的链接
+     * @see https://vercel.com/docs/projects/project-configuration#cleanurls
+     *
+     * @description
+     * 暂无效果
+     *
+     * 目前在 build-output-api 中，实现cleanUrls需要手动地写入配置文件
+     *
+     * 成本较大，目前不做投入。
+     */
+    readonly cleanUrls: true;
+    readonly git: {
+        readonly deploymentEnabled: {
+            readonly main: false;
+        };
+    };
+};
+/**
+ * 空配置文件的路径
+ * @description
+ * 生成空配置文件。这样用户在其他项目内，就不需要自己提供vercel配置文件了。
+ */
+declare const VERCEL_NULL_CONFIG_PATH = "./vercel.null.def.json";
+/** Vercel文件api指定要求的文件目录 */
+declare const VERCEL_OUTPUT_STATIC = ".vercel/output/static";
+
+/**
+ * 类型守卫：判断是否为 static 类型的部署目标
+ */
+declare function isDeployTargetBase(target: DeployTarget): target is DeployTargetBase;
+/**
+ * 类型守卫：判断是否为 userCommands 类型的部署目标
+ */
+declare function isDeployTargetWithUserCommands(target: DeployTarget): target is DeployTargetWithUserCommands;
+/**
+ * 获得 isCopyDist 配置
+ * @description
+ * 提供默认值处理
+ */
+declare function getIsCopyDist(target: DeployTargetWithUserCommands): boolean;
+/**
+ * 获得 isNeedVercelBuild 配置
+ * @description
+ * 提供默认值处理
+ */
+declare function isNeedVercelBuild(target: DeployTarget): boolean;
+
+/**
+ * 创建 deploy 命令
+ * @description
+ * 部署项目到 Vercel
+ *
+ * @example
+ * ```bash
+ * vercel-deploy-tool deploy
+ * vdt deploy
+ * ```
+ */
+declare function createDeployCommand(): Command;
+
+/**
+ * 创建 init 命令
+ * @description
+ * 初始化配置文件，生成 vercel-deploy-tool.config.ts 模板
+ *
+ * @example
+ * ```bash
+ * vercel-deploy-tool init
+ * vercel-deploy-tool init --force
+ * ```
+ */
+declare function createInitCommand(): Command;
+
+export { type DeployTarget, type DeployTargetBase, type DeployTargetType, type DeployTargetWithUserCommands, VERCEL_NULL_CONFIG, VERCEL_NULL_CONFIG_PATH, VERCEL_OUTPUT_STATIC, type VercelDeployConfig, createDeployCommand, createInitCommand, defineConfig, executeDeploymentWorkflow, getConfig, getIsCopyDist, isDeployTargetBase, isDeployTargetWithUserCommands, isNeedVercelBuild, loadConfig };