vite-plugin-taro 0.5.0 → 0.5.3

package/README.en.md

@@ -8,7 +8,15 @@
 
 Build WeChat Mini Program and Web apps with Vite 8, React 19, Taro 4, and Tailwind CSS v4.
 
-Documentation website: <https://vite-plugin-taro.netlify.app>
+Website: <https://vpt.js.org>
+
+## Quick Start
+
+```sh
+npm create vite-taro@latest my-app
+```
+
+Continue with the [Quick Start guide](https://vpt.js.org/guides/quick-start/).
 
 ### React Hot Reload in WeChat DevTools
 
@@ -21,23 +29,15 @@ Documentation website: <https://vite-plugin-taro.netlify.app>
 - **Built on Taro, beyond Taro** Use Taro components and APIs without the old webpack pipeline.
 - **Skyline ready** Use WeChat Skyline rendering globally or per page.
 
-## Create an app
-
-```sh
-npm create vite-taro@latest my-app
-```
-
-Continue with the [Quick Start guide](https://vite-plugin-taro.netlify.app/guides/quick-start/).
-
 ## Documentation
 
-- [Automatic subpackages](https://vite-plugin-taro.netlify.app/guides/automatic-subpackages/)
-- [Native WeChat components](https://vite-plugin-taro.netlify.app/guides/native-components/)
-- [Hot module replacement](https://vite-plugin-taro.netlify.app/guides/hot-module-replacement/)
-- [Skyline mode](https://vite-plugin-taro.netlify.app/guides/skyline-mode/)
-- [Migrate from Taro CLI](https://vite-plugin-taro.netlify.app/guides/migrate-from-taro/)
-- [Configuration reference](https://vite-plugin-taro.netlify.app/references/configuration/)
-- [Repository management](https://vite-plugin-taro.netlify.app/references/repository-management/)
+- [Automatic subpackages](https://vpt.js.org/guides/automatic-subpackages/)
+- [Native WeChat components](https://vpt.js.org/guides/native-components/)
+- [Hot module replacement](https://vpt.js.org/guides/hot-module-replacement/)
+- [Skyline mode](https://vpt.js.org/guides/skyline-mode/)
+- [Migrate from Taro CLI](https://vpt.js.org/guides/migrate-from-taro/)
+- [Configuration reference](https://vpt.js.org/references/configuration/)
+- [Repository management](https://vpt.js.org/references/repository-management/)
 
 ## License
 

package/README.md

@@ -8,7 +8,16 @@
 
 使用 Vite 8、React 19、Taro 4 和 Tailwind CSS v4 构建微信小程序与 Web 应用。
 
-文档网站：<https://vite-plugin-taro.netlify.app>
+官网：<https://vpt.js.org>
+
+## 快速开始
+
+```sh
+npm create vite-taro@latest my-app
+```
+
+接下来阅读[快速开始](https://vpt.js.org/guides/quick-start/)。
+
 
 ### 已支持微信开发者工具的 React 热更新
 
@@ -21,23 +30,15 @@
 - **基于 Taro，超越 Taro** 使用 Taro 组件和 API，摆脱旧式 webpack 链路。
 - **Skyline 就绪** 支持全局或按页面启用微信 Skyline 渲染模式。
 
-## 创建应用
-
-```sh
-npm create vite-taro@latest my-app
-```
-
-接下来阅读[快速开始](https://vite-plugin-taro.netlify.app/guides/quick-start/)。
-
 ## 文档
 
-- [全自动分包](https://vite-plugin-taro.netlify.app/guides/automatic-subpackages/)
-- [微信原生组件](https://vite-plugin-taro.netlify.app/guides/native-components/)
-- [开发者工具热更新](https://vite-plugin-taro.netlify.app/guides/hot-module-replacement/)
-- [Skyline 模式](https://vite-plugin-taro.netlify.app/guides/skyline-mode/)
-- [从 Taro CLI 迁移](https://vite-plugin-taro.netlify.app/guides/migrate-from-taro/)
-- [配置参考](https://vite-plugin-taro.netlify.app/references/configuration/)
-- [仓库维护](https://vite-plugin-taro.netlify.app/references/repository-management/)
+- [全自动分包](https://vpt.js.org/guides/automatic-subpackages/)
+- [微信原生组件](https://vpt.js.org/guides/native-components/)
+- [开发者工具热更新](https://vpt.js.org/guides/hot-module-replacement/)
+- [Skyline 模式](https://vpt.js.org/guides/skyline-mode/)
+- [从 Taro CLI 迁移](https://vpt.js.org/guides/migrate-from-taro/)
+- [配置参考](https://vpt.js.org/references/configuration/)
+- [仓库维护](https://vpt.js.org/references/repository-management/)
 
 ## 许可证
 

package/dist/node/plugins/client/client-taro.d.ts

@@ -1,4 +1,6 @@
 import type { Plugin } from 'vite';
+import type { VitePluginTaroTarget } from '../../../options.ts';
+/** Public facade used by transformed application API imports. */
 export declare const clientTaroApiId = "virtual:taro/api";
-/** Creates the target-neutral Taro facade plugin. */
-export declare function createClientTaroPlugin(): Plugin;
+/** Creates the shared Taro facade backed by the selected target's API implementation. */
+export declare function createClientTaroPlugin(target: VitePluginTaroTarget): Plugin;

package/dist/node/plugins/client/client-taro.js

@@ -1,19 +1,54 @@
-import { resolvePackageFile } from '../../utils/packages.js';
+import { normalizeModuleId } from '../../utils/modules.js';
+import { packageRequire, resolvePackageFile } from '../../utils/packages.js';
 import { clientTaroNativeId } from './constant.js';
+import { injectTaroFrameworkApis } from './inject-taro-framework-apis.js';
+/*
+ * Taro API resolution uses one public facade while avoiding a recursive `@tarojs/taro` import:
+ *
+ * 1. Application imports of `virtual:taro/api` or `@tarojs/taro` resolve to the physical `api.js` facade.
+ * 2. The facade itself imports `@tarojs/taro`; its importer identifies that request as the platform implementation.
+ * 3. H5 receives `@tarojs/plugin-platform-h5` APIs, while WX receives the generic `@tarojs/taro` implementation.
+ * 4. React's framework API loader transforms the facade, assigning lifecycle hooks such as `useLaunch` to the same
+ *    platform object and exposing them as named exports.
+ *
+ * The importer-sensitive second step removes the need for another public-looking virtual module while retaining one
+ * facade object for platform APIs and framework lifecycles.
+ */
+/** Public facade used by transformed application API imports. */
 export const clientTaroApiId = 'virtual:taro/api';
+const clientTaroApiPath = resolvePackageFile('dist/runtime/client/taro/api.js');
+const normalizedClientTaroApiPath = normalizeModuleId(clientTaroApiPath);
 const clientTaroComponentId = 'virtual:taro/components';
 const clientTaroModules = new Map([
-    [clientTaroApiId, resolvePackageFile('dist/runtime/client/taro/api.js')],
+    [clientTaroApiId, clientTaroApiPath],
     [clientTaroComponentId, resolvePackageFile('dist/runtime/client/taro/component.js')],
     [clientTaroNativeId, resolvePackageFile('dist/runtime/client/taro/define-native-component.js')]
 ]);
-/** Creates the target-neutral Taro facade plugin. */
-export function createClientTaroPlugin() {
+/** Creates the shared Taro facade backed by the selected target's API implementation. */
+export function createClientTaroPlugin(target) {
+    const platformTaroPath = resolvePlatformTaroPath(target);
     return {
         name: 'vpt:client-taro',
         enforce: 'pre',
-        resolveId(id) {
+        resolveId(id, importer) {
+            if (id === '@tarojs/taro') {
+                return isClientTaroFacade(importer) ? platformTaroPath : clientTaroApiPath;
+            }
             return clientTaroModules.get(id);
+        },
+        // Taro's framework loader transforms source code, so apply it only to the shared physical facade.
+        transform(code, id) {
+            if (normalizeModuleId(id) === normalizedClientTaroApiPath) {
+                return injectTaroFrameworkApis(code);
+            }
         }
     };
 }
+function resolvePlatformTaroPath(target) {
+    return target === 'h5'
+        ? packageRequire.resolve('@tarojs/plugin-platform-h5/dist/runtime/apis')
+        : packageRequire.resolve('@tarojs/taro');
+}
+function isClientTaroFacade(importer) {
+    return importer !== undefined && normalizeModuleId(importer) === normalizedClientTaroApiPath;
+}

package/dist/node/plugins/client/inject-taro-framework-apis.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Applies Taro React's standard source-to-source API loader. It imports the framework lifecycle hooks, assigns them to
+ * the facade's `taro` object, and emits matching named exports; keeping the hook inventory owned by Taro avoids drift.
+ */
+export declare function injectTaroFrameworkApis(source: string): string;

package/dist/node/plugins/client/inject-taro-framework-apis.js

@@ -0,0 +1,9 @@
+import { packageRequire } from '../../utils/packages.js';
+const apiLoader = packageRequire('@tarojs/plugin-framework-react/dist/api-loader');
+/**
+ * Applies Taro React's standard source-to-source API loader. It imports the framework lifecycle hooks, assigns them to
+ * the facade's `taro` object, and emits matching named exports; keeping the hook inventory owned by Taro avoids drift.
+ */
+export function injectTaroFrameworkApis(source) {
+    return apiLoader(source);
+}

package/dist/node/plugins/css/plugins.d.ts

@@ -1,4 +1,4 @@
 import type { PluginOption } from 'vite';
 import type { VitePluginTaroTarget } from '../../../options.ts';
-/** Creates the target-aware Tailwind CSS plugins. */
+/** Creates the target-aware Tailwind pipeline. */
 export declare function createCssPlugins(target: VitePluginTaroTarget): PluginOption[];

package/dist/node/plugins/css/plugins.js

@@ -2,83 +2,118 @@ import path from 'node:path';
 import { createStyleHandler } from '@weapp-tailwindcss/postcss';
 import { WeappTailwindcss } from 'weapp-tailwindcss/vite';
 import { packageRequire } from '../../utils/packages.js';
-// Keep the Vite plugin and the compatibility finalizer on identical WX conversion settings. A difference here can
-// make the second pass preserve browser units or apply a transformation that the first pass did not expect.
+/*
+ * CSS output order for WX:
+ *
+ *   weapp-tailwindcss output hooks
+ *       → vpt:wx-style-finalizer
+ *       → vpt:wx native companion emission
+ *
+ * All three generateBundle hooks retain hook-level `order: 'post'` and therefore execute in registration order. The
+ * upstream plugin normally also uses plugin-level `enforce: 'post'`, which would move it behind both VPT plugins and
+ * break this sequence. `alignWxGenerateBundleOrder` removes only that broader phase from upstream output hooks.
+ */
+// Tailwind belongs to VPT, not necessarily to the application. Resolving from VPT keeps strict package managers and
+// bundled development from looking for Tailwind in the application's node_modules.
 const tailwindcssBasedir = path.dirname(packageRequire.resolve('tailwindcss/package.json'));
+// Both upstream generation and VPT's final whole-file pass use one conversion policy. If these options diverge, the
+// second pass can preserve browser units or reinterpret syntax that the first pass generated.
 const wxStyleOptions = {
     cssCalc: false,
     autoprefixer: false,
     rem2rpx: true,
     px2rpx: true
 };
-/** Creates the target-aware Tailwind CSS plugins. */
+// The handler is immutable and reusable across builds; only each emitted asset's source is replaced.
+const transformWxStyle = createStyleHandler(wxStyleOptions);
+/** Creates the target-aware Tailwind pipeline. */
 export function createCssPlugins(target) {
     const wx = target === 'wx';
+    const tailwindPlugins = WeappTailwindcss({
+        // VPT is a custom Vite compiler. Using Taro's adapter would import Taro-specific CSS ownership rules.
+        appType: 'weapp-vite',
+        // WX generation rewrites Tailwind's split package imports before Vite tries to resolve them in the app.
+        // Without this, strict workspaces fail on imports such as `tailwindcss/theme.css`.
+        rewriteCssImports: wx,
+        platform: wx ? 'weapp' : 'web',
+        tailwindcssBasedir,
+        generator: {
+            target: wx ? 'weapp' : 'web'
+        },
+        cssOptions: {
+            ...wxStyleOptions,
+            // Browser output still needs vendor prefixes; WXSS does not support or need that browser pass.
+            autoprefixer: !wx
+        },
+        logLevel: 'warn'
+    }) ?? [];
     return [
-        ...(WeappTailwindcss({
-            appType: 'weapp-vite',
-            // WX must enable this for split Tailwind imports such as `tailwindcss/theme.css`. Otherwise Vite's
-            // PostCSS resolver tries to resolve those imports from the application and fails when Tailwind is owned
-            // by vpt. The web generator consumes the imports before that resolver runs, so H5 keeps the
-            // upstream default.
-            rewriteCssImports: wx,
-            // Tailwind is a plugin dependency, not an application dependency. Give weapp-tailwindcss the owning package
-            // directory explicitly so bundled development and strict package managers resolve split CSS imports equally.
-            tailwindcssBasedir,
-            generator: {
-                target: wx ? 'weapp' : 'web'
-                // webCompat: {
-                //     preset: 'legacy-web'
-                // }
-            },
-            cssOptions: {
-                ...wxStyleOptions,
-                autoprefixer: !wx
-            },
-            logLevel: 'warn'
-        }) ?? []),
-        wx ? createWxssCompatibilityFinalizer() : undefined
+        ...(wx ? tailwindPlugins.map(alignWxGenerateBundleOrder) : tailwindPlugins),
+        wx ? createWxStyleFinalizer() : undefined
     ];
 }
 /**
- * Completes WXSS adaptation that weapp-tailwindcss leaves pending after rewriting split Tailwind imports.
+ * Finalizes the one global stylesheet after upstream Tailwind generation.
  *
- * `rewriteCssImports: true` makes the early Vite transform generate the Tailwind CSS, but the non-web generator
- * also defers CSS adaptation. The generated asset is consequently browser-shaped
- * CSS containing values and syntax such as `rem`, escaped class selectors, and `@property`. It is then recorded as a
- * processed Vite asset, so the upstream output finalizer does not perform the missing complete WXSS adaptation.
- *
- * This plugin runs after the upstream finalizer, repeats only the compatibility transform, and restores the captured
- * global asset to WeChat's required `app.wxss` path. Exact path correlation leaves Page WXSS companions untouched.
- * Remove it when upstream both completes adaptation and preserves the bundler-selected filename.
+ * `cssCodeSplit: false` makes the compiler style global, but upstream can name it `.css` or `.wxss` depending on build
+ * mode. This hook converts its complete final contents once and gives it the root `app.wxss` identity required by
+ * WeChat. Running earlier loses CSS from dynamic chunks; running after native companion emission would also see Page
+ * and native-component WXSS files that must remain opaque.
  */
-function createWxssCompatibilityFinalizer() {
-    // This compatibility pass only needs the PostCSS style pipeline. Creating a complete weapp-tailwindcss context here
-    // would initialize another Tailwind compiler and source scanner for CSS that the upstream Vite plugin already generated.
-    const transformWxss = createStyleHandler(wxStyleOptions);
+function createWxStyleFinalizer() {
     return {
-        name: 'vpt:wxss-compatibility-finalizer',
-        enforce: 'post',
+        name: 'vpt:wx-style-finalizer',
         generateBundle: {
             order: 'post',
             async handler(_, bundle) {
-                // With cssCodeSplit: false the global style is the only asset with a logical
-                // .css source name, even when an earlier hook already changed its final suffix.
-                const globalStyleAsset = Object.values(bundle).find((output) => output.type === 'asset' &&
-                    (output.fileName.replaceAll('\\', '/').endsWith('.css') ||
-                        output.names.some((name) => name.replaceAll('\\', '/').endsWith('.css'))));
-                if (!globalStyleAsset)
-                    return;
-                // Both finalizers use a post-ordered generateBundle hook. Array order places this hook after the
-                // upstream finalizer, where the single Vite global style asset has its final contents and filename.
-                const source = typeof globalStyleAsset.source === 'string'
-                    ? globalStyleAsset.source
-                    : new TextDecoder().decode(globalStyleAsset.source);
-                if (source.length > 0) {
-                    globalStyleAsset.source = (await transformWxss(source)).css;
+                const styles = Object.values(bundle).filter(isStyleAsset);
+                // More than one compiler style means cssCodeSplit was re-enabled. Choosing one would silently lose CSS.
+                if (styles.length > 1) {
+                    throw new Error('WX builds require one global compiler-emitted stylesheet');
                 }
-                globalStyleAsset.fileName = 'app.wxss';
+                // CSS is optional; applications without styles do not need an empty app.wxss.
+                if (styles.length === 0)
+                    return;
+                const [style] = styles;
+                const source = typeof style.source === 'string' ? style.source : new TextDecoder().decode(style.source);
+                // generateBundle exposes the final asset as mutable so conversion and native placement remain atomic.
+                // Without the compatibility pass, browser-only selectors, escaped classes, rem and @property can reach
+                // WeChat. Without the rename, bundled development writes paths such as src/app.wxss, which WeChat does
+                // not load as the application's global stylesheet.
+                style.source = (await transformWxStyle(source)).css;
+                style.fileName = 'app.wxss';
             }
         }
     };
 }
+/**
+ * Adapts upstream plugin descriptors without mutating `weapp-tailwindcss` or patching node_modules.
+ *
+ * Vite first groups whole plugins by `enforce`, then orders individual hooks. Upstream's output plugins specify both
+ * `enforce: 'post'` and `generateBundle.order: 'post'`. The plugin-level phase overrides their earlier registration and
+ * places them after VPT's normal plugins, so VPT observes incomplete CSS. Making all of VPT post-enforced would fix that
+ * one hook while unnecessarily reordering resolution and transforms.
+ *
+ * For upstream plugins that actually own generateBundle, clone the descriptor without plugin-level enforcement. Keep
+ * hook-level `order: 'post'`: it still waits for ordinary bundle generation, while registration order becomes the sole
+ * tie-breaker between upstream generation, VPT finalization and native output. H5 descriptors remain untouched.
+ */
+function alignWxGenerateBundleOrder(pluginOption) {
+    // PluginOption permits nested arrays. Preserve their shape while adapting every concrete plugin recursively.
+    if (Array.isArray(pluginOption))
+        return pluginOption.map(alignWxGenerateBundleOrder);
+    if (!pluginOption ||
+        typeof pluginOption !== 'object' ||
+        !('enforce' in pluginOption) ||
+        pluginOption.enforce !== 'post' ||
+        !('generateBundle' in pluginOption) ||
+        pluginOption.generateBundle === undefined) {
+        return pluginOption;
+    }
+    // Clone rather than mutate: upstream may retain or reuse the descriptor returned by its factory.
+    return { ...pluginOption, enforce: undefined };
+}
+/** Selects only the compiler stylesheet; native WXSS assets are emitted by the later WX hook. */
+function isStyleAsset(output) {
+    return output.type === 'asset' && /\.(?:css|wxss)$/.test(output.fileName);
+}

package/dist/node/plugins/h5/plugins.js

@@ -34,10 +34,6 @@ function createH5TargetPlugin(options) {
                         {
                             find: /^@tarojs\/components\/dist\/components$/,
                             replacement: packageRequire.resolve('@tarojs/components/dist/components')
-                        },
-                        {
-                            find: /^@tarojs\/taro$/,
-                            replacement: packageRequire.resolve('@tarojs/plugin-platform-h5/dist/runtime/apis')
                         }
                     ]
                 },

package/dist/node/plugins/wx/placement/placer.js

@@ -98,8 +98,7 @@ export function createPlacer() {
                     // into every physical chunk filename; content identity alone is sufficient beneath that root.
                     return `${location.root}/assets/[hash].js`;
                 },
-                // Keep generic assets independent of stylesheet conventions. The CSS adapter sees Tailwind's final
-                // mutation and owns the exact global `app.wxss` identity without confusing native Page companions.
+                // Keep generic assets independent of native output identities assigned after bundling.
                 assetFileNames: 'assets/[name]-[hash][extname]'
             },
             // Rolldown rejects strict entry signatures when code-splitting groups disable recursive dependency capture.

package/dist/node/plugins/wx/plugins.js

@@ -36,8 +36,11 @@ function createWxPlugin(options) {
                 },
                 build: {
                     modulePreload: false,
+                    // Mini Program styles are intentionally global. This guarantees one compiler stylesheet for the CSS
+                    // finalizer; enabling splitting would require Page ownership and must not be silently flattened.
                     cssCodeSplit: false,
-                    // Let weapp-tailwindcss own final WXSS transformation.
+                    // Preserve readable source for the final WX compatibility pass; browser minification can emit syntax
+                    // unsupported by WeChat and would make the subsequent whole-file conversion harder to reason about.
                     cssMinify: false,
                     // No base64 assets: Taro warns on image srcs above ~2KB, and inlined
                     // images bloat the JS bundle toward the mini program package limit.
@@ -99,6 +102,12 @@ function createWxPlugin(options) {
             }
         },
         generateBundle: {
+            /*
+             * This hook is registered after createCssPlugins() and shares hook-level `order: 'post'` with the adapted
+             * upstream hooks and VPT style finalizer. Registration order therefore guarantees that app.wxss is complete
+             * before native Page/component companions are emitted. Without this order, the CSS finalizer could consume
+             * incomplete Tailwind output or mistake native WXSS companions for additional compiler styles.
+             */
             order: 'post',
             async handler(_, bundle) {
                 const subpackages = placer.getSubpackages(bundle);

package/dist/node/vite-plugin.js

@@ -8,7 +8,7 @@ import { createWxTargetPlugins } from './plugins/wx/plugins.js';
 export default function vitePluginTaro(options) {
     return [
         createConditionalDirectivePlugin(options.target),
-        createClientTaroPlugin(),
+        createClientTaroPlugin(options.target),
         ...createCssPlugins(options.target),
         ...react(),
         ...(options.target === 'wx' ? createWxTargetPlugins(options) : []),

package/dist/runtime/client/taro/api.d.ts

@@ -1,4 +1,3 @@
-import '@tarojs/plugin-framework-react/dist/runtime';
-import Taro from '@tarojs/taro';
+import taro from '@tarojs/taro';
 export * from '@tarojs/taro';
-export default Taro;
+export default taro;

package/dist/runtime/client/taro/api.js

@@ -1,9 +1,10 @@
-import '@tarojs/plugin-framework-react/dist/runtime';
-import { hooks } from '@tarojs/runtime';
-import Taro from '@tarojs/taro';
-if (hooks.isExist('initNativeApi')) {
-    hooks.call('initNativeApi', Taro);
-}
-// @ts-expect-error @tarojs/taro declares export= types, but the facade also exposes its runtime named exports.
+/*
+ * This physical module is the shared facade, not the generic Taro implementation. Its own `@tarojs/taro` request is
+ * resolved by the client plugin to the selected platform APIs, while application requests resolve back to this facade.
+ * React's API loader then extends this same object with framework lifecycle hooks.
+ */
+import taro from '@tarojs/taro';
+// Re-export platform APIs while preserving object identity for the framework loader's lifecycle assignments.
+// @ts-expect-error @tarojs/taro uses export= types while Rolldown exposes its runtime properties as named exports.
 export * from '@tarojs/taro';
-export default Taro;
+export default taro;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-taro",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "author": "sep2",
   "description": "Vite 8 plugin for building one React/Taro codebase for WeChat Mini Program and H5 targets.",
   "type": "module",
@@ -74,8 +74,8 @@
     "rolldown": "1.2.3",
     "tailwindcss": "^4.3.3",
     "weapp-tailwindcss": "^5.2.11",
-    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.5.0",
-    "@tarojs/react": "npm:vite-plugin-taro-react@0.5.0"
+    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.5.3",
+    "@tarojs/react": "npm:vite-plugin-taro-react@0.5.3"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/node/plugins/client/client-taro.ts

@@ -1,23 +1,66 @@
 import type { Plugin } from 'vite'
-import { resolvePackageFile } from '../../utils/packages.ts'
+import type { VitePluginTaroTarget } from '../../../options.ts'
+import { normalizeModuleId } from '../../utils/modules.ts'
+import { packageRequire, resolvePackageFile } from '../../utils/packages.ts'
 import { clientTaroNativeId } from './constant.ts'
+import { injectTaroFrameworkApis } from './inject-taro-framework-apis.ts'
 
+/*
+ * Taro API resolution uses one public facade while avoiding a recursive `@tarojs/taro` import:
+ *
+ * 1. Application imports of `virtual:taro/api` or `@tarojs/taro` resolve to the physical `api.js` facade.
+ * 2. The facade itself imports `@tarojs/taro`; its importer identifies that request as the platform implementation.
+ * 3. H5 receives `@tarojs/plugin-platform-h5` APIs, while WX receives the generic `@tarojs/taro` implementation.
+ * 4. React's framework API loader transforms the facade, assigning lifecycle hooks such as `useLaunch` to the same
+ *    platform object and exposing them as named exports.
+ *
+ * The importer-sensitive second step removes the need for another public-looking virtual module while retaining one
+ * facade object for platform APIs and framework lifecycles.
+ */
+/** Public facade used by transformed application API imports. */
 export const clientTaroApiId = 'virtual:taro/api'
+
+const clientTaroApiPath = resolvePackageFile('dist/runtime/client/taro/api.js')
+const normalizedClientTaroApiPath = normalizeModuleId(clientTaroApiPath)
+
 const clientTaroComponentId = 'virtual:taro/components'
+
 const clientTaroModules = new Map([
-    [clientTaroApiId, resolvePackageFile('dist/runtime/client/taro/api.js')],
+    [clientTaroApiId, clientTaroApiPath],
     [clientTaroComponentId, resolvePackageFile('dist/runtime/client/taro/component.js')],
     [clientTaroNativeId, resolvePackageFile('dist/runtime/client/taro/define-native-component.js')]
 ])
 
-/** Creates the target-neutral Taro facade plugin. */
-export function createClientTaroPlugin(): Plugin {
+/** Creates the shared Taro facade backed by the selected target's API implementation. */
+export function createClientTaroPlugin(target: VitePluginTaroTarget): Plugin {
+    const platformTaroPath = resolvePlatformTaroPath(target)
+
     return {
         name: 'vpt:client-taro',
         enforce: 'pre',
 
-        resolveId(id) {
+        resolveId(id, importer) {
+            if (id === '@tarojs/taro') {
+                return isClientTaroFacade(importer) ? platformTaroPath : clientTaroApiPath
+            }
             return clientTaroModules.get(id)
+        },
+
+        // Taro's framework loader transforms source code, so apply it only to the shared physical facade.
+        transform(code, id) {
+            if (normalizeModuleId(id) === normalizedClientTaroApiPath) {
+                return injectTaroFrameworkApis(code)
+            }
         }
     }
 }
+
+function resolvePlatformTaroPath(target: VitePluginTaroTarget): string {
+    return target === 'h5'
+        ? packageRequire.resolve('@tarojs/plugin-platform-h5/dist/runtime/apis')
+        : packageRequire.resolve('@tarojs/taro')
+}
+
+function isClientTaroFacade(importer: string | undefined): boolean {
+    return importer !== undefined && normalizeModuleId(importer) === normalizedClientTaroApiPath
+}

package/src/node/plugins/client/inject-taro-framework-apis.ts

@@ -0,0 +1,11 @@
+import { packageRequire } from '../../utils/packages.ts'
+
+const apiLoader: (source: string) => string = packageRequire('@tarojs/plugin-framework-react/dist/api-loader')
+
+/**
+ * Applies Taro React's standard source-to-source API loader. It imports the framework lifecycle hooks, assigns them to
+ * the facade's `taro` object, and emits matching named exports; keeping the hook inventory owned by Taro avoids drift.
+ */
+export function injectTaroFrameworkApis(source: string): string {
+    return apiLoader(source)
+}

package/src/node/plugins/css/plugins.ts

@@ -5,10 +5,24 @@ import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
 import type { VitePluginTaroTarget } from '../../../options.ts'
 import { packageRequire } from '../../utils/packages.ts'
 
-// Keep the Vite plugin and the compatibility finalizer on identical WX conversion settings. A difference here can
-// make the second pass preserve browser units or apply a transformation that the first pass did not expect.
+/*
+ * CSS output order for WX:
+ *
+ *   weapp-tailwindcss output hooks
+ *       → vpt:wx-style-finalizer
+ *       → vpt:wx native companion emission
+ *
+ * All three generateBundle hooks retain hook-level `order: 'post'` and therefore execute in registration order. The
+ * upstream plugin normally also uses plugin-level `enforce: 'post'`, which would move it behind both VPT plugins and
+ * break this sequence. `alignWxGenerateBundleOrder` removes only that broader phase from upstream output hooks.
+ */
+
+// Tailwind belongs to VPT, not necessarily to the application. Resolving from VPT keeps strict package managers and
+// bundled development from looking for Tailwind in the application's node_modules.
 const tailwindcssBasedir = path.dirname(packageRequire.resolve('tailwindcss/package.json'))
 
+// Both upstream generation and VPT's final whole-file pass use one conversion policy. If these options diverge, the
+// second pass can preserve browser units or reinterpret syntax that the first pass generated.
 const wxStyleOptions = {
     cssCalc: false,
     autoprefixer: false,
@@ -16,81 +30,106 @@ const wxStyleOptions = {
     px2rpx: true
 } as const
 
-/** Creates the target-aware Tailwind CSS plugins. */
+// The handler is immutable and reusable across builds; only each emitted asset's source is replaced.
+const transformWxStyle = createStyleHandler(wxStyleOptions)
+
+/** Creates the target-aware Tailwind pipeline. */
 export function createCssPlugins(target: VitePluginTaroTarget): PluginOption[] {
     const wx = target === 'wx'
 
-    return [
-        ...(WeappTailwindcss({
+    const tailwindPlugins =
+        WeappTailwindcss({
+            // VPT is a custom Vite compiler. Using Taro's adapter would import Taro-specific CSS ownership rules.
             appType: 'weapp-vite',
-            // WX must enable this for split Tailwind imports such as `tailwindcss/theme.css`. Otherwise Vite's
-            // PostCSS resolver tries to resolve those imports from the application and fails when Tailwind is owned
-            // by vpt. The web generator consumes the imports before that resolver runs, so H5 keeps the
-            // upstream default.
+            // WX generation rewrites Tailwind's split package imports before Vite tries to resolve them in the app.
+            // Without this, strict workspaces fail on imports such as `tailwindcss/theme.css`.
             rewriteCssImports: wx,
-            // Tailwind is a plugin dependency, not an application dependency. Give weapp-tailwindcss the owning package
-            // directory explicitly so bundled development and strict package managers resolve split CSS imports equally.
+            platform: wx ? 'weapp' : 'web',
             tailwindcssBasedir,
             generator: {
                 target: wx ? 'weapp' : 'web'
-                // webCompat: {
-                //     preset: 'legacy-web'
-                // }
             },
             cssOptions: {
                 ...wxStyleOptions,
+                // Browser output still needs vendor prefixes; WXSS does not support or need that browser pass.
                 autoprefixer: !wx
             },
             logLevel: 'warn'
-        }) ?? []),
-        wx ? createWxssCompatibilityFinalizer() : undefined
+        }) ?? []
+
+    return [
+        ...(wx ? tailwindPlugins.map(alignWxGenerateBundleOrder) : tailwindPlugins),
+        wx ? createWxStyleFinalizer() : undefined
     ]
 }
 
 /**
- * Completes WXSS adaptation that weapp-tailwindcss leaves pending after rewriting split Tailwind imports.
- *
- * `rewriteCssImports: true` makes the early Vite transform generate the Tailwind CSS, but the non-web generator
- * also defers CSS adaptation. The generated asset is consequently browser-shaped
- * CSS containing values and syntax such as `rem`, escaped class selectors, and `@property`. It is then recorded as a
- * processed Vite asset, so the upstream output finalizer does not perform the missing complete WXSS adaptation.
+ * Finalizes the one global stylesheet after upstream Tailwind generation.
  *
- * This plugin runs after the upstream finalizer, repeats only the compatibility transform, and restores the captured
- * global asset to WeChat's required `app.wxss` path. Exact path correlation leaves Page WXSS companions untouched.
- * Remove it when upstream both completes adaptation and preserves the bundler-selected filename.
+ * `cssCodeSplit: false` makes the compiler style global, but upstream can name it `.css` or `.wxss` depending on build
+ * mode. This hook converts its complete final contents once and gives it the root `app.wxss` identity required by
+ * WeChat. Running earlier loses CSS from dynamic chunks; running after native companion emission would also see Page
+ * and native-component WXSS files that must remain opaque.
  */
-function createWxssCompatibilityFinalizer(): Plugin {
-    // This compatibility pass only needs the PostCSS style pipeline. Creating a complete weapp-tailwindcss context here
-    // would initialize another Tailwind compiler and source scanner for CSS that the upstream Vite plugin already generated.
-    const transformWxss = createStyleHandler(wxStyleOptions)
-
+function createWxStyleFinalizer(): Plugin {
     return {
-        name: 'vpt:wxss-compatibility-finalizer',
-        enforce: 'post',
+        name: 'vpt:wx-style-finalizer',
         generateBundle: {
             order: 'post',
             async handler(_, bundle) {
-                // With cssCodeSplit: false the global style is the only asset with a logical
-                // .css source name, even when an earlier hook already changed its final suffix.
-                const globalStyleAsset = Object.values(bundle).find(
-                    (output): output is Rolldown.OutputAsset =>
-                        output.type === 'asset' &&
-                        (output.fileName.replaceAll('\\', '/').endsWith('.css') ||
-                            output.names.some((name) => name.replaceAll('\\', '/').endsWith('.css')))
-                )
-                if (!globalStyleAsset) return
-
-                // Both finalizers use a post-ordered generateBundle hook. Array order places this hook after the
-                // upstream finalizer, where the single Vite global style asset has its final contents and filename.
-                const source =
-                    typeof globalStyleAsset.source === 'string'
-                        ? globalStyleAsset.source
-                        : new TextDecoder().decode(globalStyleAsset.source)
-                if (source.length > 0) {
-                    globalStyleAsset.source = (await transformWxss(source)).css
+                const styles = Object.values(bundle).filter(isStyleAsset)
+                // More than one compiler style means cssCodeSplit was re-enabled. Choosing one would silently lose CSS.
+                if (styles.length > 1) {
+                    throw new Error('WX builds require one global compiler-emitted stylesheet')
                 }
-                globalStyleAsset.fileName = 'app.wxss'
+                // CSS is optional; applications without styles do not need an empty app.wxss.
+                if (styles.length === 0) return
+
+                const [style] = styles
+                const source = typeof style.source === 'string' ? style.source : new TextDecoder().decode(style.source)
+                // generateBundle exposes the final asset as mutable so conversion and native placement remain atomic.
+                // Without the compatibility pass, browser-only selectors, escaped classes, rem and @property can reach
+                // WeChat. Without the rename, bundled development writes paths such as src/app.wxss, which WeChat does
+                // not load as the application's global stylesheet.
+                style.source = (await transformWxStyle(source)).css
+                style.fileName = 'app.wxss'
             }
         }
     }
 }
+
+/**
+ * Adapts upstream plugin descriptors without mutating `weapp-tailwindcss` or patching node_modules.
+ *
+ * Vite first groups whole plugins by `enforce`, then orders individual hooks. Upstream's output plugins specify both
+ * `enforce: 'post'` and `generateBundle.order: 'post'`. The plugin-level phase overrides their earlier registration and
+ * places them after VPT's normal plugins, so VPT observes incomplete CSS. Making all of VPT post-enforced would fix that
+ * one hook while unnecessarily reordering resolution and transforms.
+ *
+ * For upstream plugins that actually own generateBundle, clone the descriptor without plugin-level enforcement. Keep
+ * hook-level `order: 'post'`: it still waits for ordinary bundle generation, while registration order becomes the sole
+ * tie-breaker between upstream generation, VPT finalization and native output. H5 descriptors remain untouched.
+ */
+function alignWxGenerateBundleOrder(pluginOption: PluginOption): PluginOption {
+    // PluginOption permits nested arrays. Preserve their shape while adapting every concrete plugin recursively.
+    if (Array.isArray(pluginOption)) return pluginOption.map(alignWxGenerateBundleOrder)
+
+    if (
+        !pluginOption ||
+        typeof pluginOption !== 'object' ||
+        !('enforce' in pluginOption) ||
+        pluginOption.enforce !== 'post' ||
+        !('generateBundle' in pluginOption) ||
+        pluginOption.generateBundle === undefined
+    ) {
+        return pluginOption
+    }
+
+    // Clone rather than mutate: upstream may retain or reuse the descriptor returned by its factory.
+    return { ...pluginOption, enforce: undefined }
+}
+
+/** Selects only the compiler stylesheet; native WXSS assets are emitted by the later WX hook. */
+function isStyleAsset(output: Rolldown.OutputBundle[string]): output is Rolldown.OutputAsset {
+    return output.type === 'asset' && /\.(?:css|wxss)$/.test(output.fileName)
+}

package/src/node/plugins/h5/plugins.ts

@@ -41,10 +41,6 @@ function createH5TargetPlugin(options: VitePluginTaroOptions): Plugin {
                         {
                             find: /^@tarojs\/components\/dist\/components$/,
                             replacement: packageRequire.resolve('@tarojs/components/dist/components')
-                        },
-                        {
-                            find: /^@tarojs\/taro$/,
-                            replacement: packageRequire.resolve('@tarojs/plugin-platform-h5/dist/runtime/apis')
                         }
                     ]
                 },

package/src/node/plugins/wx/placement/placer.ts

@@ -121,8 +121,7 @@ export function createPlacer() {
                     // into every physical chunk filename; content identity alone is sufficient beneath that root.
                     return `${location.root}/assets/[hash].js`
                 },
-                // Keep generic assets independent of stylesheet conventions. The CSS adapter sees Tailwind's final
-                // mutation and owns the exact global `app.wxss` identity without confusing native Page companions.
+                // Keep generic assets independent of native output identities assigned after bundling.
                 assetFileNames: 'assets/[name]-[hash][extname]'
             },
             // Rolldown rejects strict entry signatures when code-splitting groups disable recursive dependency capture.

package/src/node/plugins/wx/plugins.ts

@@ -46,8 +46,11 @@ function createWxPlugin(options: VitePluginTaroOptions): Plugin {
 
                 build: {
                     modulePreload: false,
+                    // Mini Program styles are intentionally global. This guarantees one compiler stylesheet for the CSS
+                    // finalizer; enabling splitting would require Page ownership and must not be silently flattened.
                     cssCodeSplit: false,
-                    // Let weapp-tailwindcss own final WXSS transformation.
+                    // Preserve readable source for the final WX compatibility pass; browser minification can emit syntax
+                    // unsupported by WeChat and would make the subsequent whole-file conversion harder to reason about.
                     cssMinify: false,
 
                     // No base64 assets: Taro warns on image srcs above ~2KB, and inlined
@@ -123,6 +126,12 @@ function createWxPlugin(options: VitePluginTaroOptions): Plugin {
         },
 
         generateBundle: {
+            /*
+             * This hook is registered after createCssPlugins() and shares hook-level `order: 'post'` with the adapted
+             * upstream hooks and VPT style finalizer. Registration order therefore guarantees that app.wxss is complete
+             * before native Page/component companions are emitted. Without this order, the CSS finalizer could consume
+             * incomplete Tailwind output or mistake native WXSS companions for additional compiler styles.
+             */
             order: 'post',
             async handler(_, bundle) {
                 const subpackages = placer.getSubpackages(bundle)

package/src/node/vite-plugin.ts

@@ -11,7 +11,7 @@ import { createWxTargetPlugins } from './plugins/wx/plugins.ts'
 export default function vitePluginTaro(options: VitePluginTaroOptions): PluginOption[] {
     return [
         createConditionalDirectivePlugin(options.target),
-        createClientTaroPlugin(),
+        createClientTaroPlugin(options.target),
         ...createCssPlugins(options.target),
         ...react(),
         ...(options.target === 'wx' ? createWxTargetPlugins(options) : []),

package/src/runtime/client/taro/api.ts

@@ -1,11 +1,11 @@
-import '@tarojs/plugin-framework-react/dist/runtime'
-import { hooks } from '@tarojs/runtime'
-import Taro from '@tarojs/taro'
+/*
+ * This physical module is the shared facade, not the generic Taro implementation. Its own `@tarojs/taro` request is
+ * resolved by the client plugin to the selected platform APIs, while application requests resolve back to this facade.
+ * React's API loader then extends this same object with framework lifecycle hooks.
+ */
+import taro from '@tarojs/taro'
 
-if (hooks.isExist('initNativeApi')) {
-    hooks.call('initNativeApi', Taro)
-}
-
-// @ts-expect-error @tarojs/taro declares export= types, but the facade also exposes its runtime named exports.
+// Re-export platform APIs while preserving object identity for the framework loader's lifecycle assignments.
+// @ts-expect-error @tarojs/taro uses export= types while Rolldown exposes its runtime properties as named exports.
 export * from '@tarojs/taro'
-export default Taro
+export default taro