@amaster.ai/vite-plugins 1.0.0-beta.4 → 1.0.0-beta.40

package/dist/index.d.cts

@@ -8,7 +8,7 @@ declare function componentIdPlugin(): Plugin;
 
 /**
  * Vite plugin: Inject editor bridge script
- * Injects bridge.js in development mode by reading the built bridge script
+ * Injects minimal bridge that loads external script from platform
  */
 declare function editorBridgePlugin(): Plugin;
 
@@ -20,13 +20,247 @@ declare function routesExposePlugin(options?: {
     routesFilePath?: string;
 }): Plugin;
 
+interface TaroStyleAdapterOptions {
+    /**
+     * Design width for responsive scaling (default: 375)
+     * Should match Taro config's designWidth
+     */
+    designWidth?: number;
+    /**
+     * Maximum viewport width to scale (default: 750)
+     * Beyond this width, font-size stays fixed
+     */
+    maxWidth?: number;
+    /**
+     * Base font size in pixels (default: 12)
+     * Should match Taro config's baseFontSize
+     */
+    baseFontSize?: number;
+    /**
+     * Minimum root font size in pixels (default: 12)
+     * Should match Taro config's minRootSize
+     */
+    minRootSize?: number;
+    /**
+     * Maximum root font size in pixels (default: 24)
+     * Should match Taro config's maxRootSize
+     */
+    maxRootSize?: number;
+}
+/**
+ * Taro H5 样式适配插件
+ *
+ * 功能：
+ * 1. 动态计算根字号，使 H5 的 rem 与小程序的 rpx 行为对齐
+ * 2. 隐藏 Taro 页面容器的滚动条，用于编辑器 iframe 预览
+ *
+ * 原理：
+ * - 小程序 rpx: 1rpx = 屏幕宽度 / 750
+ * - H5 rem: Taro 把 rpx 转成 rem，基于 baseFontSize
+ * - 本插件动态设置 html font-size，使 rem 的实际像素值与 rpx 对齐
+ *
+ * 注意：此插件会覆盖 Taro 默认注入的根字号脚本，配置需与 Taro pxtransform 保持一致
+ *
+ * @example
+ * ```ts
+ * // In Taro config/dev.ts
+ * import { taroStyleAdapterPlugin } from '@amaster.ai/vite-plugins'
+ *
+ * export default {
+ *   compiler: {
+ *     type: 'vite',
+ *     vitePlugins: [
+ *       taroStyleAdapterPlugin({
+ *         designWidth: 375,
+ *         baseFontSize: 12,
+ *         minRootSize: 12,
+ *         maxRootSize: 24
+ *       })
+ *     ]
+ *   }
+ * }
+ * ```
+ */
+declare function taroStyleAdapterPlugin(options?: TaroStyleAdapterOptions): Plugin;
+
+/**
+ * Taro Environment Variables Injection Helper
+ *
+ * Automatically injects environment variables into Taro's defineConstants
+ * so that they will be replaced at build time.
+ *
+ * @example
+ * ```ts
+ * // In Taro config/index.ts
+ * import { injectTaroEnv } from '@amaster.ai/vite-plugins/taro-env-inject'
+ *
+ * export default defineConfig({
+ *   defineConstants: {
+ *     ...injectTaroEnv()
+ *   }
+ * })
+ * ```
+ */
+interface TaroEnvInjectOptions {
+    /**
+     * Additional environment variable names to inject
+     * @default []
+     */
+    additional?: string[];
+    /**
+     * Whether to inject all TARO_APP_* prefixed variables
+     * @default true
+     */
+    autoInjectTaroApp?: boolean;
+    /**
+     * Whether to inject all VITE_* prefixed variables
+     * @default true
+     */
+    autoInjectVite?: boolean;
+}
+/**
+ * Inject environment variables into Taro's defineConstants
+ *
+ * This function reads environment variables and formats them for Taro's defineConstants.
+ * Taro will replace these at build time, converting `process.env.XXX` to actual values.
+ */
+declare function injectTaroEnv(options?: TaroEnvInjectOptions): Record<string, string>;
+/**
+ * Inject specific environment variables for amaster.ai mini-program builds
+ *
+ * This is a convenience function that injects the standard environment variables
+ * used by @amaster.ai/http-client for API base URL configuration.
+ */
+declare function injectAmasterEnv(): Record<string, string>;
+
+/**
+ * PostCSS 插件：H5 模式下将 rpx 预转换为 px
+ *
+ * 问题背景：
+ * - Taro 的 pxtransform 在 H5 模式下会处理 rpx，但它把 rpx 值直接除以 rootValue
+ * - 导致 96rpx 被转成 8rem（96/12），实际显示为 96px
+ * - 而正确应该是：96rpx = 48px = 4rem = 48px
+ *
+ * 解决方案：
+ * - 在 pxtransform 之前，先把 rpx 转成 px（rpx / 2）
+ * - 然后 pxtransform 会正确地把 px 转成 rem（px / 12）
+ *
+ * 转换链路：96rpx → 48px → 4rem → 48px（正确）
+ *
+ * @example
+ * ```ts
+ * // In Taro config/index.ts
+ * import { rpx2pxPlugin } from '@amaster.ai/vite-plugins'
+ *
+ * // 在 postcss-config-loader-plugin 中使用
+ * {
+ *   name: 'postcss-config-loader-plugin',
+ *   config(config) {
+ *     if (typeof config.css?.postcss === 'object') {
+ *       config.css?.postcss.plugins?.unshift(tailwindcss())
+ *       // H5 模式下添加 rpx2px 插件
+ *       if (process.env.TARO_ENV === 'h5') {
+ *         config.css?.postcss.plugins?.unshift(rpx2pxPlugin())
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface Rpx2pxPluginOptions {
+    /**
+     * rpx 到 px 的转换比例（默认 2）
+     * 即 1rpx = 1/ratio px
+     * 默认值 2 表示 2rpx = 1px（基于 375 设计稿）
+     */
+    ratio?: number;
+}
+interface PostCSSDeclaration {
+    value: string;
+}
+interface PostCSSPlugin {
+    postcssPlugin: string;
+    Declaration: (decl: PostCSSDeclaration) => void;
+}
+declare function rpx2pxPlugin(options?: Rpx2pxPluginOptions): PostCSSPlugin;
+
+/**
+ * Vite plugin: JSX Source Tagger
+ * Intercepts react/jsx-dev-runtime to add source information to DOM elements
+ * Only enabled in development mode
+ */
+declare function jsxSourceTaggerPlugin(): Plugin;
+
+/**
+ * Vite plugin: Tailwind Config Sync
+ * Generates a JSON file from tailwind.config.ts for runtime access
+ * Only enabled in development mode
+ */
+declare function tailwindConfigSyncPlugin(options?: {
+    configPath?: string;
+}): Plugin;
+
 interface DevToolsOptions {
+    /**
+     * 是否为 Taro 项目
+     * - true: 启用 Taro 相关插件（taroStyleAdapterPlugin、rpx2pxPlugin）
+     * - false: 禁用 Taro 相关插件
+     * - undefined: 自动检测（通过 process.env.TARO_ENV 判断，默认为 false）
+     */
+    isTaro?: boolean;
+    /**
+     * Taro style adapter options
+     * Controls H5 responsive scaling to match mini-program rpx behavior
+     * 仅在 isTaro 为 true 时生效
+     */
+    styleAdapter?: TaroStyleAdapterOptions;
+    /**
+     * 是否启用 JSX Source Tagger（通过 Symbol 标记元素源码位置）
+     * 默认：开发模式启用
+     */
+    jsxSourceTagger?: boolean;
+    /**
+     * 是否启用 Tailwind Config 同步（生成 JSON 文件）
+     * 默认：开发模式启用
+     */
+    tailwindConfigSync?: boolean;
+    /**
+     * Tailwind 配置文件路径
+     * 默认：./tailwind.config.ts
+     */
+    tailwindConfigPath?: string;
 }
 /**
  * 开发工具插件集合，简化调用，vite.config.ts 直接 devTools() 即可
- * @param _options 预留参数，用于未来扩展配置（例如可选择性启用某些插件）
+ *
+ * @param options 配置项
+ * @param options.isTaro 是否为 Taro 项目（默认根据 TARO_ENV 自动判断）
+ * @param options.styleAdapter Taro H5 样式适配配置，designWidth 应与 Taro config 一致
  * @returns Plugin[] Vite 插件数组
+ *
+ * @example
+ * ```ts
+ * // Taro 项目 - config/dev.ts
+ * import devTools from "@amaster.ai/vite-plugins";
+ *
+ * export default {
+ *   compiler: {
+ *     type: 'vite',
+ *     vitePlugins: [devTools({ isTaro: true })]
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // React 项目 - vite.config.ts
+ * import devTools from "@amaster.ai/vite-plugins";
+ *
+ * export default {
+ *   plugins: [devTools()]  // isTaro 默认为 false
+ * }
+ * ```
  */
-declare function devTools(_options?: DevToolsOptions): Plugin[];
+declare function devTools(options?: DevToolsOptions): Plugin[];
 
-export { type DevToolsOptions, componentIdPlugin, devTools as default, editorBridgePlugin, routesExposePlugin };
+export { type DevToolsOptions, type Rpx2pxPluginOptions, type TaroStyleAdapterOptions, componentIdPlugin, devTools as default, editorBridgePlugin, injectAmasterEnv, injectTaroEnv, jsxSourceTaggerPlugin, routesExposePlugin, rpx2pxPlugin, tailwindConfigSyncPlugin, taroStyleAdapterPlugin };

package/dist/index.d.ts

@@ -8,7 +8,7 @@ declare function componentIdPlugin(): Plugin;
 
 /**
  * Vite plugin: Inject editor bridge script
- * Injects bridge.js in development mode by reading the built bridge script
+ * Injects minimal bridge that loads external script from platform
  */
 declare function editorBridgePlugin(): Plugin;
 
@@ -20,13 +20,247 @@ declare function routesExposePlugin(options?: {
     routesFilePath?: string;
 }): Plugin;
 
+interface TaroStyleAdapterOptions {
+    /**
+     * Design width for responsive scaling (default: 375)
+     * Should match Taro config's designWidth
+     */
+    designWidth?: number;
+    /**
+     * Maximum viewport width to scale (default: 750)
+     * Beyond this width, font-size stays fixed
+     */
+    maxWidth?: number;
+    /**
+     * Base font size in pixels (default: 12)
+     * Should match Taro config's baseFontSize
+     */
+    baseFontSize?: number;
+    /**
+     * Minimum root font size in pixels (default: 12)
+     * Should match Taro config's minRootSize
+     */
+    minRootSize?: number;
+    /**
+     * Maximum root font size in pixels (default: 24)
+     * Should match Taro config's maxRootSize
+     */
+    maxRootSize?: number;
+}
+/**
+ * Taro H5 样式适配插件
+ *
+ * 功能：
+ * 1. 动态计算根字号，使 H5 的 rem 与小程序的 rpx 行为对齐
+ * 2. 隐藏 Taro 页面容器的滚动条，用于编辑器 iframe 预览
+ *
+ * 原理：
+ * - 小程序 rpx: 1rpx = 屏幕宽度 / 750
+ * - H5 rem: Taro 把 rpx 转成 rem，基于 baseFontSize
+ * - 本插件动态设置 html font-size，使 rem 的实际像素值与 rpx 对齐
+ *
+ * 注意：此插件会覆盖 Taro 默认注入的根字号脚本，配置需与 Taro pxtransform 保持一致
+ *
+ * @example
+ * ```ts
+ * // In Taro config/dev.ts
+ * import { taroStyleAdapterPlugin } from '@amaster.ai/vite-plugins'
+ *
+ * export default {
+ *   compiler: {
+ *     type: 'vite',
+ *     vitePlugins: [
+ *       taroStyleAdapterPlugin({
+ *         designWidth: 375,
+ *         baseFontSize: 12,
+ *         minRootSize: 12,
+ *         maxRootSize: 24
+ *       })
+ *     ]
+ *   }
+ * }
+ * ```
+ */
+declare function taroStyleAdapterPlugin(options?: TaroStyleAdapterOptions): Plugin;
+
+/**
+ * Taro Environment Variables Injection Helper
+ *
+ * Automatically injects environment variables into Taro's defineConstants
+ * so that they will be replaced at build time.
+ *
+ * @example
+ * ```ts
+ * // In Taro config/index.ts
+ * import { injectTaroEnv } from '@amaster.ai/vite-plugins/taro-env-inject'
+ *
+ * export default defineConfig({
+ *   defineConstants: {
+ *     ...injectTaroEnv()
+ *   }
+ * })
+ * ```
+ */
+interface TaroEnvInjectOptions {
+    /**
+     * Additional environment variable names to inject
+     * @default []
+     */
+    additional?: string[];
+    /**
+     * Whether to inject all TARO_APP_* prefixed variables
+     * @default true
+     */
+    autoInjectTaroApp?: boolean;
+    /**
+     * Whether to inject all VITE_* prefixed variables
+     * @default true
+     */
+    autoInjectVite?: boolean;
+}
+/**
+ * Inject environment variables into Taro's defineConstants
+ *
+ * This function reads environment variables and formats them for Taro's defineConstants.
+ * Taro will replace these at build time, converting `process.env.XXX` to actual values.
+ */
+declare function injectTaroEnv(options?: TaroEnvInjectOptions): Record<string, string>;
+/**
+ * Inject specific environment variables for amaster.ai mini-program builds
+ *
+ * This is a convenience function that injects the standard environment variables
+ * used by @amaster.ai/http-client for API base URL configuration.
+ */
+declare function injectAmasterEnv(): Record<string, string>;
+
+/**
+ * PostCSS 插件：H5 模式下将 rpx 预转换为 px
+ *
+ * 问题背景：
+ * - Taro 的 pxtransform 在 H5 模式下会处理 rpx，但它把 rpx 值直接除以 rootValue
+ * - 导致 96rpx 被转成 8rem（96/12），实际显示为 96px
+ * - 而正确应该是：96rpx = 48px = 4rem = 48px
+ *
+ * 解决方案：
+ * - 在 pxtransform 之前，先把 rpx 转成 px（rpx / 2）
+ * - 然后 pxtransform 会正确地把 px 转成 rem（px / 12）
+ *
+ * 转换链路：96rpx → 48px → 4rem → 48px（正确）
+ *
+ * @example
+ * ```ts
+ * // In Taro config/index.ts
+ * import { rpx2pxPlugin } from '@amaster.ai/vite-plugins'
+ *
+ * // 在 postcss-config-loader-plugin 中使用
+ * {
+ *   name: 'postcss-config-loader-plugin',
+ *   config(config) {
+ *     if (typeof config.css?.postcss === 'object') {
+ *       config.css?.postcss.plugins?.unshift(tailwindcss())
+ *       // H5 模式下添加 rpx2px 插件
+ *       if (process.env.TARO_ENV === 'h5') {
+ *         config.css?.postcss.plugins?.unshift(rpx2pxPlugin())
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface Rpx2pxPluginOptions {
+    /**
+     * rpx 到 px 的转换比例（默认 2）
+     * 即 1rpx = 1/ratio px
+     * 默认值 2 表示 2rpx = 1px（基于 375 设计稿）
+     */
+    ratio?: number;
+}
+interface PostCSSDeclaration {
+    value: string;
+}
+interface PostCSSPlugin {
+    postcssPlugin: string;
+    Declaration: (decl: PostCSSDeclaration) => void;
+}
+declare function rpx2pxPlugin(options?: Rpx2pxPluginOptions): PostCSSPlugin;
+
+/**
+ * Vite plugin: JSX Source Tagger
+ * Intercepts react/jsx-dev-runtime to add source information to DOM elements
+ * Only enabled in development mode
+ */
+declare function jsxSourceTaggerPlugin(): Plugin;
+
+/**
+ * Vite plugin: Tailwind Config Sync
+ * Generates a JSON file from tailwind.config.ts for runtime access
+ * Only enabled in development mode
+ */
+declare function tailwindConfigSyncPlugin(options?: {
+    configPath?: string;
+}): Plugin;
+
 interface DevToolsOptions {
+    /**
+     * 是否为 Taro 项目
+     * - true: 启用 Taro 相关插件（taroStyleAdapterPlugin、rpx2pxPlugin）
+     * - false: 禁用 Taro 相关插件
+     * - undefined: 自动检测（通过 process.env.TARO_ENV 判断，默认为 false）
+     */
+    isTaro?: boolean;
+    /**
+     * Taro style adapter options
+     * Controls H5 responsive scaling to match mini-program rpx behavior
+     * 仅在 isTaro 为 true 时生效
+     */
+    styleAdapter?: TaroStyleAdapterOptions;
+    /**
+     * 是否启用 JSX Source Tagger（通过 Symbol 标记元素源码位置）
+     * 默认：开发模式启用
+     */
+    jsxSourceTagger?: boolean;
+    /**
+     * 是否启用 Tailwind Config 同步（生成 JSON 文件）
+     * 默认：开发模式启用
+     */
+    tailwindConfigSync?: boolean;
+    /**
+     * Tailwind 配置文件路径
+     * 默认：./tailwind.config.ts
+     */
+    tailwindConfigPath?: string;
 }
 /**
  * 开发工具插件集合，简化调用，vite.config.ts 直接 devTools() 即可
- * @param _options 预留参数，用于未来扩展配置（例如可选择性启用某些插件）
+ *
+ * @param options 配置项
+ * @param options.isTaro 是否为 Taro 项目（默认根据 TARO_ENV 自动判断）
+ * @param options.styleAdapter Taro H5 样式适配配置，designWidth 应与 Taro config 一致
  * @returns Plugin[] Vite 插件数组
+ *
+ * @example
+ * ```ts
+ * // Taro 项目 - config/dev.ts
+ * import devTools from "@amaster.ai/vite-plugins";
+ *
+ * export default {
+ *   compiler: {
+ *     type: 'vite',
+ *     vitePlugins: [devTools({ isTaro: true })]
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // React 项目 - vite.config.ts
+ * import devTools from "@amaster.ai/vite-plugins";
+ *
+ * export default {
+ *   plugins: [devTools()]  // isTaro 默认为 false
+ * }
+ * ```
  */
-declare function devTools(_options?: DevToolsOptions): Plugin[];
+declare function devTools(options?: DevToolsOptions): Plugin[];
 
-export { type DevToolsOptions, componentIdPlugin, devTools as default, editorBridgePlugin, routesExposePlugin };
+export { type DevToolsOptions, type Rpx2pxPluginOptions, type TaroStyleAdapterOptions, componentIdPlugin, devTools as default, editorBridgePlugin, injectAmasterEnv, injectTaroEnv, jsxSourceTaggerPlugin, routesExposePlugin, rpx2pxPlugin, tailwindConfigSyncPlugin, taroStyleAdapterPlugin };