@moluoxixi/vite-config 0.0.27 → 0.0.30

package/README.md

@@ -16,7 +16,7 @@ export default viteConfig(({ mode }) => {
   return {
     rootPath: path.resolve(),
     mode: {
-      base: { VITE_GLOB_APP_TITLE: viteEnv.VITE_GLOB_APP_TITLE, VITE_GLOB_APP_CODE: viteEnv.VITE_GLOB_APP_CODE, VITE_AUTO_ROUTES: true },
+      base: { VITE_APP_TITLE: viteEnv.VITE_APP_TITLE, VITE_APP_CODE: viteEnv.VITE_APP_CODE, VITE_AUTO_ROUTES: true },
       development: { VITE_DEVTOOLS: true },
       production: {},
     },

package/es/index.mjs

@@ -1,10 +1,10 @@
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-import "vue";
 import fs from "node:fs";
 import path from "node:path";
 import process$1 from "node:process";
+import "vue";
 import "dotenv";
 import tailwindcss from "@tailwindcss/postcss";
 import autoprefixer from "autoprefixer";
@@ -46,6 +46,80 @@ function deepMerge(target, source) {
     return acc;
   }, { ...target });
 }
+function validateMutuallyExclusive(values, defaultKey) {
+  const keys = Object.keys(values);
+  const enabledKeys = [];
+  for (const key of keys) {
+    if (values[key] === true) {
+      enabledKeys.push(key);
+    }
+  }
+  if (enabledKeys.length > 1) {
+    const keysStr = enabledKeys.join("、");
+    const allKeysStr = keys.join("、");
+    const selectedKey = enabledKeys.includes(defaultKey) ? defaultKey : enabledKeys[0];
+    console.warn(
+      `[validateMutuallyExclusive] ${allKeysStr} 只能启用一个，但当前启用了：${keysStr}。已自动选择：${String(selectedKey)}`
+    );
+    const result2 = {};
+    for (const key of keys) {
+      result2[key] = key === selectedKey;
+    }
+    return result2;
+  }
+  const hasEnabledKey = enabledKeys.length > 0;
+  const result = {};
+  for (const key of keys) {
+    if (!hasEnabledKey && defaultKey && key === defaultKey) {
+      result[key] = true;
+    } else {
+      result[key] = values[key] ?? false;
+    }
+  }
+  return result;
+}
+function detectFramework(config, rootDir) {
+  const root = rootDir || process$1.cwd();
+  const packageJsonPath = path.resolve(root, "package.json");
+  let vue = config.vue;
+  let react = config.react;
+  let vitepress = config.vitepress;
+  const hasExplicitFramework = vue === true || react === true || vitepress === true;
+  if (!hasExplicitFramework) {
+    let dependencies = {};
+    let devDependencies = {};
+    if (fs.existsSync(packageJsonPath)) {
+      try {
+        const packageJsonContent = fs.readFileSync(packageJsonPath, "utf-8");
+        const packageJson = JSON.parse(packageJsonContent);
+        dependencies = packageJson.dependencies || {};
+        devDependencies = packageJson.devDependencies || {};
+      } catch (error) {
+        console.warn(`无法读取 package.json: ${packageJsonPath}`, error);
+      }
+    }
+    if (vue === void 0) {
+      if (dependencies.vue || devDependencies.vue) {
+        vue = true;
+      }
+    }
+    if (react === void 0 && vue !== true) {
+      if (dependencies.react || devDependencies.react) {
+        react = true;
+      }
+    }
+    if (vitepress === void 0 && vue !== true && react !== true) {
+      if (dependencies.vitepress || devDependencies.vitepress) {
+        vitepress = true;
+      }
+    }
+  }
+  return {
+    vue: vue ?? false,
+    react: react ?? false,
+    vitepress: vitepress ?? false
+  };
+}
 function changeHtmlClassPrefix(htmlString = "", oldPrefix = "", newPrefix = "") {
   const regex = new RegExp(
     `(class|style)\\s*:\\s*((["']((${oldPrefix}\\b)-).*["'])|((_normalizeClass|_normalizeStyle)\\(.*(${oldPrefix}\\b)-.*\\)))`,
@@ -99,12 +173,9 @@ function addScopedAndReplacePrefixPlugin({
 }
 async function getViteConfig(Config, params) {
   const configResult = typeof Config === "function" ? Config(params) : Config;
-  if (!configResult || !configResult.rootPath) {
-    throw new Error("rootPath is required in ViteConfig");
-  }
   const config = configResult;
   const { mode = "base" } = params || {};
-  const rootPath = config.rootPath;
+  const rootPath = config.rootPath || process.cwd();
   const modeConfig = config.mode || {};
   const baseConfig = modeConfig.base || {};
   const currentModeConfig = modeConfig[mode] || {};
@@ -128,13 +199,24 @@ async function getViteConfig(Config, params) {
     qiankun = config.qiankun,
     namespace = config.namespace,
     dropConsole = config.dropConsole,
-    vue = config.vue ?? true,
-    react = config.react,
-    vitepress = config.vitepress
+    vue: vueRaw = config.vue,
+    react: reactRaw = config.react,
+    vitepress: vitepressRaw = config.vitepress
   } = viteEnv;
+  const frameworkResult = detectFramework(
+    {
+      vue: vueRaw,
+      react: reactRaw,
+      vitepress: vitepressRaw
+    },
+    rootPath
+  );
+  const { vue, react, vitepress } = validateMutuallyExclusive(
+    frameworkResult,
+    "vue"
+  );
   const appTitle = config.appTitle;
   const appCode = config.appCode;
-  const isOnlyVue = !vitepress && !react && vue;
   const isVueOrVitepress = vue || vitepress;
   const envSystemCode = isDev && !qiankunDevMode ? "el" : namespace ?? appCode;
   const plugins = [
@@ -146,21 +228,32 @@ async function getViteConfig(Config, params) {
       }
     })
   ];
-  if (isOnlyVue) {
+  if (vue) {
     const pluginVue = await dynamicImport(import("@vitejs/plugin-vue"));
     plugins.push(pluginVue());
   }
+  if (react) {
+    const pluginReact = await dynamicImport(import("@vitejs/plugin-react"));
+    plugins.push(pluginReact());
+  }
   if (isVueOrVitepress) {
     const vueJsx = await dynamicImport(import("@vitejs/plugin-vue-jsx"));
     plugins.push(vueJsx());
   }
   if (pageRoutes) {
     const Pages = await dynamicImport(import("vite-plugin-pages"));
+    const extensions = [];
+    if (vue) {
+      extensions.push("vue");
+    }
+    if (react) {
+      extensions.push("tsx", "jsx");
+    }
     plugins.push(Pages(
       deepMerge(
         {
           dirs: "src/pages",
-          extensions: [isOnlyVue && "vue"].filter(Boolean),
+          extensions,
           exclude: [
             "**/components/**",
             "**/__tests__/**"
@@ -170,11 +263,11 @@ async function getViteConfig(Config, params) {
       )
     ));
   }
-  if (isDev && devtools) {
+  if (isDev && devtools && isVueOrVitepress) {
     const vueDevTools = await dynamicImport(import("vite-plugin-vue-devtools"));
     plugins.push(vueDevTools());
   }
-  if (autoImport) {
+  if (autoImport && isVueOrVitepress) {
     const AutoImport = await dynamicImport(import("unplugin-auto-import/vite"));
     const ElementPlusResolverModule = await dynamicImport(import("unplugin-vue-components/resolvers"));
     const { ElementPlusResolver } = ElementPlusResolverModule;
@@ -182,21 +275,21 @@ async function getViteConfig(Config, params) {
       deepMerge(
         {
           imports: ["vue"],
-          resolvers: isVueOrVitepress ? [ElementPlusResolver()] : [],
+          resolvers: [ElementPlusResolver()],
           dts: path.resolve(rootPath, "./typings/auto-imports.d.ts")
         },
         autoImport
       )
     ));
   }
-  if (autoComponent) {
+  if (autoComponent && isVueOrVitepress) {
     const Components = await dynamicImport(import("unplugin-vue-components/vite"));
     const ElementPlusResolverModule = await dynamicImport(import("unplugin-vue-components/resolvers"));
     const { ElementPlusResolver } = ElementPlusResolverModule;
     plugins.push(Components(
       deepMerge(
         {
-          resolvers: isVueOrVitepress ? [ElementPlusResolver()] : [],
+          resolvers: [ElementPlusResolver()],
           globs: [],
           dts: path.resolve(rootPath, "./typings/components.d.ts")
         },
@@ -295,6 +388,7 @@ async function getViteConfig(Config, params) {
         {
           strategies: "generateSW",
           registerType: "autoUpdate",
+          // 开发模式下也启用
           devOptions: {
             enabled: true
           },
@@ -302,7 +396,7 @@ async function getViteConfig(Config, params) {
           manifest: {
             id: appCode ? `/${appCode}/` : "/",
             start_url: appCode ? `/${appCode}/` : "/",
-            name: appTitle || "Vue 应用",
+            name: appTitle || "应用",
             short_name: appTitle || "应用",
             description: "渐进式 Web 应用",
             display: "standalone",
@@ -340,7 +434,7 @@ async function getViteConfig(Config, params) {
       }));
     }
   }
-  if (autoRoutes) {
+  if (autoRoutes && isVueOrVitepress) {
     const AutoRoutesPlugin = await dynamicImport(Promise.resolve().then(() => index));
     plugins.push(AutoRoutesPlugin(
       deepMerge(
@@ -389,6 +483,15 @@ async function getViteConfig(Config, params) {
               if (id.includes("@vue") || id.includes("vue")) {
                 return "vue-vendor";
               }
+              if (id.includes("antd") || id.includes("@ant-design")) {
+                return "antd-vendor";
+              }
+              if (id.includes("react-dom")) {
+                return "react-dom-vendor";
+              }
+              if (id.includes("react")) {
+                return "react-vendor";
+              }
               return "vendor";
             }
           }
@@ -520,13 +623,23 @@ function createMatcher(prefixes) {
 }
 class VirtualModuleState {
   constructor() {
+    /** 标记服务器是否正在关闭，避免关闭阶段再触发无效操作 */
     __publicField(this, "isServerClosing", false);
+    /** 标记初始化是否完成，初始化期间的变化会被延迟处理 */
     __publicField(this, "isInitialized", false);
+    /** 标记初始化期间是否有文件变化，初始化完成后会处理这些变化 */
     __publicField(this, "hasPendingChange", false);
+    /** HMR 热更新的防抖函数，lodash-es debounce 返回的函数有 cancel 方法，可以手动取消 */
     __publicField(this, "hmrDebouncedInvalidate");
+    /** watchChange 钩子的防抖函数，用于清理模块缓存 */
     __publicField(this, "watchChangeDebouncedClear");
+    /** 文件监听器的防抖函数 */
     __publicField(this, "watcherDebouncedInvalidate");
   }
+  /**
+   * 清理所有防抖定时器
+   * 在服务器关闭时调用，确保不会有待执行的防抖任务
+   */
   clearAll() {
     var _a, _b, _c;
     (_a = this.hmrDebouncedInvalidate) == null ? void 0 : _a.cancel();
@@ -702,12 +815,23 @@ function createVirtualPlugin(userConfig) {
     performInvalidate(server);
   };
   return {
+    /**
+     * 解析虚拟模块 ID
+     * 当 import 语句引用虚拟模块时，Vite 会调用此方法
+     * @param args - resolveId 的所有参数
+     * @returns 如果匹配虚拟模块 ID，返回该 ID；否则返回 undefined
+     */
     resolveId(...args) {
       const [id] = args;
       if (id === VIRTUAL_MODULE_ID || id.startsWith(`${VIRTUAL_MODULE_ID}/`))
         return id;
       return callUserHook(resolveId, this, ...args);
     },
+    /**
+     * 配置解析完成钩子
+     * 在 Vite 配置解析完成后调用，用于初始化监听路径和生成类型声明文件
+     * @param args - configResolved 的所有参数
+     */
     configResolved(...args) {
       const [config] = args;
       resolvedViteConfig = config;
@@ -719,6 +843,11 @@ function createVirtualPlugin(userConfig) {
       writeDtsFile(config, rootDir, dts, generateDts);
       callUserHook(configResolved, this, ...args);
     },
+    /**
+     * 配置开发服务器钩子
+     * 在开发服务器启动时调用，用于设置文件监听、信号处理和清理逻辑
+     * @param args - configureServer 的所有参数
+     */
     configureServer(...args) {
       var _a;
       const [server] = args;
@@ -759,6 +888,16 @@ function createVirtualPlugin(userConfig) {
       });
       callUserHook(configureServer, this, ...args);
     },
+    /**
+     * 处理热更新钩子
+     * 当 Vite 检测到文件变化时调用，用于触发虚拟模块的失效和更新
+     * @param args - handleHotUpdate 的所有参数
+     * @returns 空数组，表示不阻止其他插件的处理
+     * @remarks
+     * - 使用防抖机制避免频繁触发
+     * - 初始化期间的变化会被延迟处理
+     * - 只处理匹配监听路径的文件变化
+     */
     handleHotUpdate(...args) {
       const [ctx] = args;
       const { server } = ctx;
@@ -786,6 +925,16 @@ function createVirtualPlugin(userConfig) {
       state.hmrDebouncedInvalidate();
       return callUserHook(handleHotUpdate, this, ...args) || [];
     },
+    /**
+     * 监听文件变化钩子
+     * 当 Vite 的依赖预构建或文件系统检测到变化时调用
+     * 主要用于清理模块缓存，让下次加载时重新生成
+     * @param args - watchChange 的所有参数
+     * @remarks
+     * - 与 handleHotUpdate 不同，此钩子主要用于清理缓存，不触发 HMR
+     * - 使用防抖机制避免频繁清理
+     * - 初始化期间的变化会被延迟处理
+     */
     watchChange(...args) {
       try {
         const [id] = args;
@@ -817,6 +966,16 @@ function createVirtualPlugin(userConfig) {
       } catch {
       }
     },
+    /**
+     * 加载虚拟模块内容
+     * 当 import 语句引用虚拟模块时，Vite 会调用此方法获取模块代码
+     * @param args - load 的所有参数
+     * @returns 模块代码字符串，如果 ID 不匹配则返回 undefined
+     * @remarks
+     * - 支持同步和异步的 generateModule 函数
+     * - 生成的代码会被缓存，直到模块被失效
+     * - 子路径导入（如 'virtual:routes/sub'）会传入完整 ID 给 generateModule
+     */
     async load(...args) {
       const [id] = args;
       if (id === VIRTUAL_MODULE_ID || id.startsWith(`${VIRTUAL_MODULE_ID}/`)) {
@@ -826,6 +985,7 @@ function createVirtualPlugin(userConfig) {
       }
       return await callUserHook(load, this, ...args);
     },
+    // 使用 rest 参数包含所有其他未使用的钩子（包括 name, transform, enforce 等）
     ...restHooks
   };
 }
@@ -972,6 +1132,7 @@ function createAutoRoutesPlugin({ routeConfig, virtualModuleId, dts, root, eager
       root,
       watch: watchGlobs,
       enforce: "pre",
+      // 生成虚拟模块代码：仅负责产出字符串，监听/HMR/缓存由工厂统一处理
       generateModule: () => {
         const imports = [];
         const routes = [];
@@ -994,9 +1155,9 @@ function createAutoRoutesPlugin({ routeConfig, virtualModuleId, dts, root, eager
           ${findDefaultRouteHandle}
 
           const findParentRoute = ${findParentRouteHandle}
-
+          // 用于routes
           const generateRoutes = ${generateRoutes};
-
+          // 用于导出
           const findDefaultRoute = ${findDefaultRouteHandle};
 
           const routes = ${routesCode}.flat().filter(Boolean);
@@ -1005,6 +1166,7 @@ function createAutoRoutesPlugin({ routeConfig, virtualModuleId, dts, root, eager
           export default routes;
         `;
       },
+      // 生成类型声明文件
       generateDts: () => `// 此文件由ViteConfig自动生成，请勿手动修改
 declare module 'virtual:auto-routes' {
   interface RouteModule {

package/es/src/_types/index.d.ts

@@ -19,35 +19,116 @@ export type QiankunPlugin = (name: string, options?: {
     useDevMode?: boolean;
 }) => PluginOption;
 export type CDNOptions = Parameters<typeof importToCDN>[0] & {
+    /**
+     * CDN的基本url
+     */
     baseUrl?: string;
+    /**
+     * dev环境是否启用CDN
+     */
     enableInDevMode?: boolean;
 };
 export type VisualizerOptions = Parameters<typeof visualizer>[0];
+/**
+ * 插件配置类型，仅在 ModeConfig 中使用
+ */
 export interface PluginConfig {
+    /**
+     * AutoImport配置，true表示使用默认配置，对象表示覆盖默认配置
+     */
     autoImport?: boolean | unpluginAutoImportOptions;
+    /**
+     * Components配置，true表示使用默认配置，对象表示覆盖默认配置
+     */
     autoComponent?: boolean | (unpluginVueComponentsOptions & {
+        /**
+         * 需要排除的element-plus组件
+         */
         elementExcludes?: string[];
+        /**
+         * 除resolve规则外，额外需要引入的组件所需匹配规则
+         */
         globs?: string[];
     });
+    /**
+     * 压缩配置，true表示使用默认配置，对象表示覆盖默认配置
+     */
     compression?: boolean | CompressionOptions;
+    /**
+     * 图片压缩配置，true表示使用默认配置，对象表示覆盖默认配置
+     */
     imagemin?: boolean | ImageminOptions;
+    /**
+     * CDN配置，true表示使用默认配置，对象表示覆盖默认配置
+     */
     cdn?: boolean | CDNOptions;
+    /**
+     * 包预览配置，true表示使用默认配置，对象表示覆盖默认配置
+     */
     visualizer?: boolean | VisualizerOptions;
+    /**
+     * 自动路由配置，true表示使用默认配置，对象表示覆盖默认配置
+     */
     autoRoutes?: boolean | AutoRoutesConfig;
+    /**
+     * 页面路由配置（vite-plugin-pages），true表示使用默认配置，对象表示覆盖默认配置
+     */
     pageRoutes?: boolean | PagesOptions;
+    /**
+     * 是否启用vue-devtools
+     */
     devtools?: boolean;
+    /**
+     * 项目端口
+     */
     port?: number;
+    /**
+     * 是否在npm run dev时，自动打开浏览器
+     */
     open?: boolean;
+    /**
+     * dev环境是否启用qiankun
+     */
     qiankunDevMode?: boolean;
+    /**
+     * 是否启用qiankun
+     */
     qiankun?: boolean;
+    /**
+     * 命名空间，启用后在非dev环境下的envSystemCode将等于此值
+     */
     namespace?: string;
+    /**
+     * 是否在打包时，删除console和debugger
+     */
     dropConsole?: boolean;
+    /**
+     * PWA配置，true表示使用默认配置，对象表示覆盖默认配置
+     */
     pwa?: boolean | VitePWAOptions;
+    /**
+     * Code Inspector配置，true表示使用默认配置，对象表示覆盖默认配置
+     */
     codeInspector?: boolean | Parameters<typeof import('code-inspector-plugin').codeInspectorPlugin>[0];
+    /**
+     * 是否是vitepress
+     */
     vitepress?: boolean;
+    /**
+     * 是否是vue
+     */
     vue?: boolean;
+    /**
+     * 是否是react
+     */
     react?: boolean;
+    /**
+     * 项目标题
+     */
     appTitle?: string;
+    /**
+     * 项目code
+     */
     appCode?: string;
 }
 export interface ModeConfig extends PluginConfig {
@@ -65,13 +146,32 @@ export interface RouteConfig {
     [prefix: string]: string | string[] | objRouteConfig;
 }
 export interface AutoRoutesConfig {
+    /**
+     * 路由配置
+     */
     routeConfig: RouteConfig;
+    /**
+     * 虚拟模块ID
+     */
     virtualModuleId?: string;
+    /**
+     * 声明文件路径，true表示使用默认路径，false表示不生成声明文件
+     */
     dts?: string | boolean;
+    /**
+     * 项目根目录路径
+     */
     root?: string;
 }
 export interface Config extends PluginConfig {
-    rootPath: string;
+    /**
+     * 根目录
+     * 如果不传入，将使用 process.cwd() 作为默认值
+     */
+    rootPath?: string;
+    /**
+     * 环境配置
+     */
     mode?: {
         base?: ModeConfig;
         development?: ModeConfig;

package/es/src/_utils/detectFramework.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 框架配置类型
+ */
+export interface FrameworkConfig {
+    /**
+     * Vue 框架配置
+     */
+    vue?: boolean;
+    /**
+     * React 框架配置
+     */
+    react?: boolean;
+    /**
+     * VitePress 框架配置
+     */
+    vitepress?: boolean;
+}
+/**
+ * 框架检测结果类型
+ */
+export interface FrameworkResult {
+    /**
+     * Vue 框架
+     */
+    vue: boolean;
+    /**
+     * React 框架
+     */
+    react: boolean;
+    /**
+     * VitePress 框架
+     */
+    vitepress: boolean;
+}
+/**
+ * 检测项目依赖中的框架
+ * 优先级：显示传入 > 检测，且优先级为 vue/react > vitepress
+ * @param config - 框架配置对象，包含 vue、react、vitepress
+ * @param rootDir - 项目根目录，如果不传入则使用 process.cwd()
+ * @returns 检测后的框架配置对象
+ */
+export declare function detectFramework(config: FrameworkConfig, rootDir?: string): FrameworkResult;

package/es/src/_utils/getEnv.d.ts

@@ -1,7 +1,22 @@
 import { objType } from '../../../_types/index.ts';
 export declare function isDevFn(mode: string): boolean;
 export declare function isProdFn(mode: string): boolean;
+/**
+ * Whether to generate package preview
+ */
 export declare function isReportMode(): boolean;
+/**
+ * 将环境变量中的字符串值转换为对应的 JavaScript 数据类型
+ */
 export declare function wrapperEnv(env: Record<string, string>): objType;
+/**
+ * Get the environment variables starting with the specified prefix
+ * @param match prefix
+ * @param confFiles ext
+ */
 export declare function getEnvConfig(match?: string, confFiles?: string[]): {};
+/**
+ * Get user root directory
+ * @param dir file path
+ */
 export declare function getRootPath(...dir: string[]): string;

package/es/src/_utils/index.d.ts

@@ -1 +1,2 @@
+export * from './detectFramework.ts';
 export * from './getEnv.ts';