vite-plugin-taro 0.0.4 → 0.0.6

package/README.md

@@ -3,68 +3,85 @@
 [![npm version](https://img.shields.io/npm/v/vite-plugin-taro.svg)](https://www.npmjs.com/package/vite-plugin-taro)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Vite 8 plugin for building one React 19 + Taro 4 app as either Web (`h5`) or WeChat Mini Program (`wx`).
+简体中文 | [English](README.en.md)
 
-## Highlights
+使用最新标准前端技术栈 Vite 8、React 19 和 Tailwind CSS v4 构建微信小程序。
 
-- Builds the same React/Taro pages for `h5` and `wx` targets.
-- Uses React 19-compatible Taro React packages published by this monorepo.
-- Generates Taro-style app/page entries instead of requiring generated files in your app source.
-- Emits WeChat Mini Program assets: `app.json`, page JSON, WXML, WXS, WXSS, and CommonJS chunks.
-- Boots H5 with Taro's official router/runtime and component CSS.
-- Handles Tailwind CSS v4 for H5 and transforms Tailwind output for WeChat Mini Programs.
-- Strips inactive Taro-style conditional compilation blocks before Vite parses code.
-- Provides app-facing facades for Taro APIs and components.
+`vite-plugin-taro` 适用于希望使用 Taro 跨平台 React 组件和 API，但更偏好 Vite/Rolldown 而非 Taro webpack 构建器的应用。插件会为你生成应用/页面入口、目标运行时别名、H5 路由启动代码、微信端配套文件、Tailwind 处理，以及条件编译。
 
-## Compatibility
+在线演示：<https://sep2.github.io/vite-plugin-taro>。如何在本地运行，请参见[示例应用](#示例应用)。
 
-| Dependency | Supported version |
-| --- | --- |
-| Node.js | `^20.19.0` or `>=22.12.0` |
-| Vite | `^8.0.0` |
-| React / React DOM | `^19.0.0` |
-| Taro runtime packages | `4.2.0` |
-| Tailwind CSS | `4.x` |
+## 安装
+
+```sh
+pnpm add -D vite-plugin-taro
+```
 
-## Install
+你的应用还必须提供 Vite 8、React 19、React DOM 19、TypeScript 以及 React 类型包。如果应用尚未安装它们，请安装缺失的包：
 
 ```sh
-pnpm add -D vite vite-plugin-taro
 pnpm add react react-dom
+pnpm add -D vite typescript @types/react @types/react-dom
 ```
 
-## Package exports
+你不应再直接依赖任何 `@tarojs/*` 包。如果已经依赖，请将它们移除。
 
-| Import | Use |
-| --- | --- |
-| `vite-plugin-taro/vite` | Recommended Vite plugin entry. Exports the default plugin plus option/target types. |
-| `vite-plugin-taro` | Same plugin entry as `vite-plugin-taro/vite`. |
-| `vite-plugin-taro/components` | Re-export of Taro React components. Use this in application code. |
-| `vite-plugin-taro/taro` | Taro API facade. Use this instead of importing `@tarojs/taro` directly. |
-| `vite-plugin-taro/shim/h5` | Internal H5 runtime shim used by generated entries. |
-| `vite-plugin-taro/shim/wx` | Internal WeChat runtime shim used by generated entries. |
+## 快速开始
 
-Application code should normally use only `vite-plugin-taro/components` and `vite-plugin-taro/taro`.
+下面的示例会创建如下源码结构：
 
-## Minimal setup
+```text
+my-app/
+├── index.html
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+└── src/
+    ├── app.css
+    ├── app.ts
+    └── pages/
+        └── index/
+            └── index.tsx
+```
 
-### Vite config
+你也可以参考 [packages/loan-genius](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius) 中的示例布局。
+
+### 1. 添加 TypeScript 声明
+
+将插件客户端类型添加到 `tsconfig.json`，让 TypeScript 识别虚拟模块：
+
+```json
+{
+    "compilerOptions": {
+        "jsx": "react-jsx",
+        "moduleResolution": "bundler",
+        "types": ["vite/client", "vite-plugin-taro/client"]
+    },
+    "include": ["src"]
+}
+```
+
+### 2. 配置 Vite
+
+创建 `vite.config.ts`，并从环境变量中选择插件目标：
 
 ```ts
 import { defineConfig, loadEnv } from 'vite'
-import vitePluginTaro, { type VitePluginTaroTarget } from 'vite-plugin-taro/vite'
+import vitePluginTaro, { type VitePluginTaroTarget } from 'vite-plugin-taro'
 
-function getTarget(value: string | undefined): VitePluginTaroTarget {
-    if (value === 'h5' || value === 'wx') return value
-    throw new Error('VITE_PLUGIN_TARO_TARGET must be "h5" or "wx".')
+const targetEnvName = 'VITE_PLUGIN_TARO_TARGET'
+
+function getTarget(env: Record<string, string>): VitePluginTaroTarget {
+    const target = env[targetEnvName]
+    if (target === 'h5' || target === 'wx') return target
+    throw new Error(`${targetEnvName} must be "h5" or "wx".`)
 }
 
 export default defineConfig(({ mode }) => {
     const env = loadEnv(mode, process.cwd(), 'VITE_PLUGIN_TARO_')
-    const target = getTarget(env.VITE_PLUGIN_TARO_TARGET)
+    const target = getTarget(env)
 
     return {
-        base: target === 'h5' ? './' : undefined,
         build: {
             outDir: `dist/${target}`
         },
@@ -80,9 +97,16 @@ export default defineConfig(({ mode }) => {
                         }
                     }
                 ],
-                appJson: {},
+                appJson: {
+                    window: {
+                        navigationBarTitleText: 'Demo',
+                        navigationBarBackgroundColor: '#ffffff'
+                    }
+                },
                 projectConfigJson: {
-                    appid: env.VITE_PLUGIN_TARO_WECHAT_APP_ID || 'touristappid'
+                    appid: env.VITE_PLUGIN_TARO_WECHAT_APP_ID || 'touristappid',
+                    projectname: 'demo',
+                    compileType: 'miniprogram'
                 },
                 sitemapJson: {
                     rules: [{ action: 'allow', page: '*' }]
@@ -93,54 +117,121 @@ export default defineConfig(({ mode }) => {
 })
 ```
 
-### App component
+重要约定：
 
-`app` points to a module that default-exports the root React app component.
+- 每次 Vite 运行时，`target` 必须是 `h5` 或 `wx`。
+- `app` 是根 React 应用组件模块。它应默认导出应用组件。
+- 每个 `pages[].path` 都映射到 `src/${path}.tsx` 文件。例如，`pages/index/index` 要求存在 `src/pages/index/index.tsx`。
+- `appJson.pages` 会根据 `pages` 生成；你在 `appJson` 中传入的任何 `pages` 字段都会被覆盖。
+- 插件不会读取 Taro CLI 配置文件，例如 `config/index.ts`、`app.config.ts` 或页面 `config.ts` 文件。请通过插件选项传入应用和页面配置。
+
+### 3. 创建应用组件
+
+`src/app.ts` 是共享应用包装器。它会通过 `children` 接收当前页面。
 
 ```tsx
-// src/app.ts
+import Taro from 'virtual:taro/api'
 import type { PropsWithChildren } from 'react'
-import Taro from 'vite-plugin-taro/taro'
 import './app.css'
 
-export default function App({ children }: PropsWithChildren) {
+function App({ children }: PropsWithChildren) {
     Taro.useLaunch(() => {
-        console.log('App launch')
+        console.log('App launched')
     })
 
     return children
 }
+
+export default App
 ```
 
-### Page component
+从应用组件中导入全局样式。它们会包含在 H5 输出中，并在微信构建中收集到 `app.wxss`。
 
-Each `pages[].path` maps to `src/${path}.tsx`.
+### 4. 创建页面组件
+
+`src/pages/index/index.tsx` 是 `pages/index/index` 对应的 React 组件。
 
 ```tsx
-// src/pages/index/index.tsx
-import { Text, View } from 'vite-plugin-taro/components'
-import Taro from 'vite-plugin-taro/taro'
+import { Button, Text, View } from 'virtual:taro/components'
+import Taro from 'virtual:taro/api'
 
 export default function IndexPage() {
     const windowInfo = Taro.getWindowInfo()
 
     return (
-        <View>
+        <View className="p-4">
             <Text>Viewport width: {windowInfo.windowWidth}</Text>
+            <Button
+                onClick={() => {
+                    Taro.showToast({ title: 'Hello from Taro' })
+                }}
+            >
+                Show toast
+            </Button>
         </View>
     )
 }
 ```
 
-### HTML shell for H5
+在应用代码中使用这些导入：
+
+| 导入 | 用途 |
+| --- | --- |
+| `virtual:taro/components` | Taro React 组件，例如 `View`、`Text`、`Button`、`Image` 和 `ScrollView`。 |
+| `virtual:taro/api` | Taro API 和 hooks，例如 `Taro.navigateTo`、`Taro.getWindowInfo` 和 `Taro.useLaunch`。 |
+
+不要在应用代码中直接导入 `@tarojs/*` 包。此插件禁止且不支持直接使用 `@tarojs/*`，因为这可能绕过目标特定的运行时别名和 H5 API 转换。请只使用 `virtual:taro/api` 和 `virtual:taro/components`。
+
+### 5. 添加 H5 HTML 外壳
 
-For H5 builds, keep a normal Vite `index.html`. The plugin injects the generated Taro H5 entry automatically.
+对于 H5，请保留一个普通的 Vite `index.html`，并包含 `#app` 挂载节点。插件会自动注入生成的 Taro H5 入口，因此你不需要普通 Vite 的 `src/main.tsx` 脚本。
 
 ```html
-<div id="app"></div>
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Taro Vite App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>
 ```
 
-## Plugin options
+### 6. 添加脚本
+
+```json
+{
+    "scripts": {
+        "dev:h5": "NODE_ENV=development VITE_PLUGIN_TARO_TARGET=h5 vite",
+        "build:h5": "NODE_ENV=production VITE_PLUGIN_TARO_TARGET=h5 vite build",
+        "dev:wx": "NODE_ENV=development VITE_PLUGIN_TARO_TARGET=wx vite build --watch",
+        "build:wx": "NODE_ENV=production VITE_PLUGIN_TARO_TARGET=wx vite build"
+    }
+}
+```
+
+在 Windows shell 中，请使用 `cross-env`。
+
+### 7. 运行每个目标
+
+```sh
+pnpm dev:h5       # 启动 H5 开发服务器
+pnpm build:h5     # 构建 dist/h5
+pnpm build:wx     # 构建 dist/wx
+pnpm dev:wx       # 以 watch 模式重新构建 dist/wx
+```
+
+在微信开发者工具中打开生成的 `dist/wx` 目录。
+
+| 目标 | 含义 | 输出目录 |
+| --- | --- | --- |
+| `h5` | H5 生产输出。 | `dist/h5` |
+| `wx` | 开发/生产模式下的微信小程序。 | `dist/wx` |
+
+## 选项
 
 ```ts
 type VitePluginTaroTarget = 'wx' | 'h5'
@@ -160,37 +251,36 @@ type VitePluginTaroOptions = {
 }
 ```
 
-| Option | Description |
+| 选项 | 描述 |
 | --- | --- |
-| `target` | Active target for this Vite invocation: `h5` or `wx`. |
-| `app` | Source file that default-exports the root React app component. |
-| `pages` | Ordered page list. The order becomes `app.json.pages` and the H5 route order. |
-| `pages[].path` | Taro-style route and output path without extension, for example `pages/index/index`. The page component must exist at `src/${path}.tsx`. |
-| `pages[].config` | Page JSON config merged into WeChat page JSON and H5 route config. |
-| `appJson` | Base app config. The plugin overwrites `pages` from `options.pages`. |
-| `projectConfigJson` | WeChat `project.config.json` content emitted for `wx` builds. |
-| `sitemapJson` | WeChat `sitemap.json` content emitted for `wx` builds. |
+| `target` | 本次 Vite 调用的活动目标。Web 使用 `h5`，微信小程序使用 `wx`。 |
+| `app` | 默认导出根 React 应用组件的源码文件，例如 `src/app.ts` 或 `src/app.tsx`。 |
+| `pages` | 有序页面列表。该顺序会成为 `app.json.pages` 和 H5 路由顺序。 |
+| `pages[].path` | 不带扩展名的 Taro 风格路由和输出路径，例如 `pages/index/index`。页面组件必须存在于 `src/${path}.tsx`。 |
+| `pages[].config` | 合并到生成的微信页面 JSON 和 H5 路由配置中的页面配置。 |
+| `appJson` | 基础应用配置。插件会根据 `options.pages` 覆盖 `pages` 字段。 |
+| `projectConfigJson` | `wx` 构建时输出的微信 `project.config.json` 内容。即使当前目标是 `h5`，选项类型也要求提供它。 |
+| `sitemapJson` | `wx` 构建时输出的微信 `sitemap.json` 内容。即使当前目标是 `h5`，选项类型也要求提供它。 |
 
-## Scripts in your app
+## 样式
 
-Use separate scripts or environment files to build each target.
+你可以使用普通 CSS、CSS Modules 或 Tailwind CSS v4。
 
-```json
-{
-    "scripts": {
-        "dev:h5": "VITE_PLUGIN_TARO_TARGET=h5 vite",
-        "build:h5": "VITE_PLUGIN_TARO_TARGET=h5 vite build",
-        "dev:wx": "VITE_PLUGIN_TARO_TARGET=wx vite build --watch",
-        "build:wx": "VITE_PLUGIN_TARO_TARGET=wx vite build"
-    }
-}
+对于 Tailwind CSS v4，请从全局 CSS 文件（例如 `src/app.css`）导入 Tailwind：
+
+```css
+@import "tailwindcss/theme.css";
+@import "tailwindcss/preflight.css";
+@import "tailwindcss/utilities.css";
+
+@source "./";
 ```
 
-On Windows shells, use `cross-env` or your package manager's environment-file support.
+插件会为 `h5` 构建注册 `@tailwindcss/vite`，并为 `wx` 构建注册 `weapp-tailwindcss`。对于 `wx`，Vite 输出的 CSS 会被收集到 `app.wxss`，并为每个页面生成配套的 `.wxss` 文件。
 
-## Conditional compilation
+## 条件编译
 
-The plugin strips inactive Taro-style conditional comment blocks before Vite parses source files. Supported source types include TypeScript, JavaScript, JSX/TSX, CSS, Sass, Less, and Stylus.
+插件会在 Vite 解析源码之前移除非活动的 Taro 风格条件注释块。该能力适用于 `node_modules` 之外的 TypeScript、JavaScript、JSX/TSX、CSS、Sass、Less 和 Stylus 文件。
 
 ```ts
 // #ifdef wx
@@ -210,32 +300,19 @@ console.log('fallback')
 // #endif
 ```
 
-Supported directives are `#ifdef`, `#ifndef`, `#if`, `#elif`, `#else`, and `#endif`. Expressions support target tokens with `!`, `&&`, and `||`.
-
-## Styling
+支持的指令包括 `#ifdef`、`#ifndef`、`#if`、`#elif`、`#else` 和 `#endif`。条件使用插件目标标记 `h5` 和 `wx`；`#if` 表达式支持 `!`、`&&` 和 `||`。
 
-- H5 builds use `@tailwindcss/vite`.
-- WeChat builds use `weapp-tailwindcss` with Tailwind CSS v4 support, `px`/`rem` to `rpx` conversion, and WeChat-compatible selector output.
-- CSS emitted by Vite for `wx` is collected into `app.wxss`; page-level `.wxss` files are emitted as companions.
-- Import global styles from the app component, for example `import './app.css'`.
+## 按目标输出
 
-## Target outputs
+### H5
 
-### `h5`
+对于 `target: 'h5'`，插件会向 `index.html` 注入生成模块，导入 Taro 的 H5 组件样式，根据 `pages` 构建路由记录，并使用 Taro 的 hash-history 路由挂载应用。路由使用配置中的页面路径，例如 `#/pages/index/index`。
 
-The plugin injects a virtual module into `index.html`, imports Taro's component styles, creates H5 route records from `pages`, mounts the root app, and uses Taro's hash-history router.
+### 微信小程序
 
-Typical output directory:
+对于 `target: 'wx'`，插件会配置 Vite/Rolldown，输出微信兼容的 CommonJS chunk 和小程序配套文件。
 
-```text
-dist/h5/
-```
-
-### `wx`
-
-The plugin configures Rolldown for WeChat-compatible CommonJS chunks and emits Mini Program companion files.
-
-Typical output directory:
+典型输出：
 
 ```text
 dist/wx/
@@ -252,25 +329,129 @@ dist/wx/
 └── pages/**
 ```
 
-Open the `wx` output directory with WeChat DevTools.
+请使用微信开发者工具打开 `dist/wx`；不要打开源码项目目录。
+
+## 从 Taro 迁移
+
+你可以保留大多数 React 页面组件、业务逻辑、资源和样式，但构建入口会从 Taro CLI 配置迁移到 Vite 配置。
+
+迁移检查清单：
+
+1. 安装 `vite-plugin-taro`，并创建包含 `vitePluginTaro(...)` 的 `vite.config.ts`。
+2. 将应用配置和页面配置移入插件选项。插件不会读取 Taro CLI 文件，例如 `config/index.ts`、`app.config.ts` 或页面 `config.ts` 文件。
+3. 在 `pages` 中注册每个页面。每个页面路径都必须匹配 `src/${path}.tsx`。
+4. 将 Taro 脚本替换为设置 `VITE_PLUGIN_TARO_TARGET=h5` 或 `VITE_PLUGIN_TARO_TARGET=wx` 的 Vite 脚本。
+5. 对于 H5，添加普通 Vite `index.html`，其中包含 `<div id="app"></div>`，且不要添加单独的 `src/main.tsx` 入口。
+6. 将应用中的 `@tarojs/*` 导入替换为插件虚拟模块。
+
+之前：
+
+```tsx
+import Taro from '@tarojs/taro'
+import { Text, View } from '@tarojs/components'
+```
+
+之后：
+
+```tsx
+import Taro from 'virtual:taro/api'
+import { Text, View } from 'virtual:taro/components'
+```
+
+应用代码中禁止直接导入 `@tarojs/*`。请让插件负责 Taro 运行时解析，使 H5 和微信构建都获得正确的目标特定别名。
+
+## 示例应用
+
+示例应用位于 [`packages/loan-genius`](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius)。它展示了页面约定、目标选择、H5 路由、Tailwind 样式和微信输出。
+
+```sh
+git clone https://github.com/sep2/vite-plugin-taro.git
+
+# 安装依赖
+pnpm install
+
+# 运行一次，用于生成打过补丁的 Taro 包
+pnpm prepare:taro
+
+# 构建插件供示例应用使用
+pnpm build:plugin
+
+# 以开发模式运行 H5 示例应用
+pnpm dev:sample:h5
+
+# 将示例应用构建为 H5 输出并预览
+pnpm build:sample:h5
+pnpm preview:sample:h5
+
+# 运行微信示例应用
+pnpm dev:sample:wx
+
+# 将示例应用构建为微信输出
+pnpm build:sample:wx
+```
+
+使用微信开发者工具打开 `packages/loan-genius/dist/wx`，以测试小程序输出。
 
-## Limitations
 
-- Supported targets are currently `h5` and WeChat Mini Program (`wx`). Other Taro platforms are not generated by this plugin.
-- Page modules follow the fixed convention `src/${page.path}.tsx`.
-- `projectConfigJson` and `sitemapJson` are required by the option type even though they are only emitted for `wx` builds.
-- Import Taro APIs/components through `vite-plugin-taro/taro` and `vite-plugin-taro/components`; direct `@tarojs/*` imports can bypass target aliases.
+## 开发此仓库
 
-## Troubleshooting
+```sh
+pnpm install
+pnpm prepare:taro
+pnpm build:plugin
+pnpm typecheck
+```
+
+常用脚本：
 
-| Problem | Check |
+| 脚本 | 描述 |
 | --- | --- |
-| `VITE_PLUGIN_TARO_TARGET must be "h5" or "wx"` | Set the target environment variable before running Vite. |
-| A page cannot be resolved | Confirm that `pages[].path` has a matching `src/${path}.tsx` file. |
-| H5 component styles load in the wrong order | Make sure the plugin is registered and `vite-plugin-taro/components` is used for components. |
-| WeChat DevTools cannot open the project | Check `projectConfigJson.appid` and open the generated `dist/wx` directory, not the source package. |
-| Taro APIs behave differently per target | Import from `vite-plugin-taro/taro` so the plugin can apply target-specific runtime aliases and H5 API transforms. |
+| `pnpm prepare:taro` | 从上游 npm tarball 和本地补丁文件重新生成打过补丁的 React 19 Taro 包。 |
+| `pnpm build:plugin` | 将 `packages/vite-plugin-taro` 构建到 `dist`。 |
+| `pnpm typecheck` | 使用 `tsgo` 对插件和示例应用进行类型检查。 |
+| `pnpm lint` | 运行 Biome 检查。 |
+| `pnpm format` | 应用 Biome 格式化。 |
+| `pnpm dev:sample:h5` | 以 Vite 开发模式启动 H5 示例应用。请先构建插件。 |
+| `pnpm dev:sample:wx` | 以 watch 模式构建微信小程序示例。请先构建插件。 |
+| `pnpm build:sample:h5` | 将 H5 示例应用构建到 `packages/loan-genius/dist/h5`。 |
+| `pnpm preview:sample:h5` | 预览构建后的 H5 示例。 |
+| `pnpm build:sample:wx` | 将微信小程序示例构建到 `packages/loan-genius/dist/wx`。 |
+| `pnpm publish:dry` | 对包校验和发布流程进行 dry-run。 |
+| `pnpm publish:all` | 按依赖顺序发布所有公开包。 |
+
+## 限制
+
+- 目前只生成 `h5` 和 `wx` 目标。
+- 应用代码不得直接导入 `@tarojs/*` 包。
+
+
+## 故障排查
+
+| 问题 | 检查项 |
+| --- | --- |
+| `VITE_PLUGIN_TARO_TARGET must be "h5" or "wx"` | 在脚本或 `.env` 文件中设置目标环境变量。 |
+| 页面无法解析 | 确认 `pages[].path` 有匹配的 `src/${path}.tsx` 文件。 |
+| H5 显示空白页 | 确保 `index.html` 中保留 `<div id="app"></div>`，已注册插件，并避免添加单独的默认 Vite `main.tsx` 入口。 |
+| Taro API 缺失或行为不同 | 移除应用代码中直接导入的 `@tarojs/*`，并从 `virtual:taro/api` 导入 Taro。 |
+| 组件在 H5 上渲染时缺少预期样式 | 从 `virtual:taro/components` 导入组件，并确保 `h5` 目标启用了插件。 |
+| 微信开发者工具无法打开应用 | 打开生成的 `dist/wx` 文件夹，并检查 `projectConfigJson.appid`。 |
+| Tailwind 类没有生效 | 确保全局 CSS 导入 Tailwind，并包含覆盖源码文件的 `@source` 路径。 |
+
+## 发布流程
+
+发布前先验证可发布包：
+
+```sh
+pnpm publish:dry
+```
+
+按要求顺序发布所有公开包：
+
+```sh
+pnpm publish:all
+```
+
 
-## License
+## 许可证
 
-MIT. See [`LICENSE`](LICENSE).
+MIT

package/client.d.ts

@@ -0,0 +1,9 @@
+declare module 'virtual:taro/api' {
+    import Taro = require('@tarojs/taro')
+    export = Taro
+    export default Taro
+}
+
+declare module 'virtual:taro/components' {
+    export * from '@tarojs/components'
+}

package/dist/vite/constants.js

@@ -1,3 +1,10 @@
 import { createRequire } from 'node:module';
+import path from 'node:path';
 export const isProd = process.env.NODE_ENV === 'production';
 export const nodeRequire = createRequire(import.meta.url);
+const packageRoot = path.dirname(nodeRequire.resolve('vite-plugin-taro/package.json'));
+export const h5ShimImportPath = normalizeFileImport(path.join(packageRoot, 'dist/shim/h5.js'));
+export const wxShimImportPath = normalizeFileImport(path.join(packageRoot, 'dist/shim/wx.js'));
+function normalizeFileImport(filePath) {
+    return filePath.replace(/\\/g, '/');
+}

package/dist/vite/targets/h5.js

@@ -1,7 +1,8 @@
 import babel from '@rolldown/plugin-babel';
 import react from '@vitejs/plugin-react';
-import { isProd, nodeRequire } from '../constants.js';
+import { h5ShimImportPath, isProd, nodeRequire } from '../constants.js';
 import { createPageComponentImport } from '../utils.js';
+import { virtualTaroApiId } from '../virtual-modules.js';
 const virtualH5Id = 'virtual:vite-plugin-taro/h5';
 const patchStencilCssOrder = true;
 /**
@@ -76,13 +77,13 @@ export function createH5SupportPlugins() {
             plugins: [rewriteStencilStyleInsertion]
         }));
     }
-    // Mirrors Taro H5: rewrite default Taro.xxx calls from vite-plugin-taro/taro to named H5 API imports.
+    // Mirrors Taro H5: rewrite default Taro.xxx calls from virtual:taro/api to named H5 API imports.
     plugins.push(babel({
         plugins: [
             [
                 nodeRequire.resolve('babel-plugin-transform-taroapi'),
                 {
-                    packageName: 'vite-plugin-taro/taro',
+                    packageName: virtualTaroApiId,
                     definition: nodeRequire(nodeRequire.resolve('@tarojs/plugin-platform-h5/dist/definition.json'))
                 }
             ]
@@ -156,7 +157,7 @@ import {
     createRouter,
     handleAppMount,
     window
-} from 'vite-plugin-taro/shim/h5'
+} from ${JSON.stringify(h5ShimImportPath)}
 import React from 'react'
 import ReactDOM from 'react-dom/client'
 import AppComponent from '${context.appComponentImport}'

package/dist/vite/targets/wx.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { recursiveMerge } from '@tarojs/helper';
 import { Weapp as WechatPlatform } from '@tarojs/plugin-platform-weapp';
-import { isProd, nodeRequire } from '../constants.js';
+import { isProd, nodeRequire, wxShimImportPath } from '../constants.js';
 import { createPageComponentImport, normalizeModuleId } from '../utils.js';
 const virtualWxAppId = 'virtual:vite-plugin-taro/wx/app';
 const virtualWxCompId = 'virtual:vite-plugin-taro/wx/comp';
@@ -29,7 +29,7 @@ export function loadWxVirtualModule(cleanId, context) {
     }
 }
 const taroWechatComponentsReactPath = nodeRequire.resolve('@tarojs/plugin-platform-weapp/dist/components-react');
-const vitePluginTaroSourcePath = normalizeModuleId(path.dirname(nodeRequire.resolve('vite-plugin-taro/vite')));
+const vitePluginTaroSourcePath = normalizeModuleId(path.dirname(nodeRequire.resolve('vite-plugin-taro')));
 const taroVersion = String(nodeRequire('@tarojs/runtime/package.json').version);
 /**
  * Configures wx target entry, output, and chunk layout.
@@ -160,7 +160,7 @@ export function emitWechatImplicitChunksForVirtualApp(emitter, context, cleanId)
  */
 export function createWxAppEntry(context) {
     const wechatAppConfigCode = JSON.stringify(context.appConfig);
-    return `import { createReactApp, ReactDOM } from 'vite-plugin-taro/shim/wx'
+    return `import { createReactApp, ReactDOM } from ${JSON.stringify(wxShimImportPath)}
 import React from 'react'
 import AppComponent from '${context.appComponentImport}'
 
@@ -176,7 +176,7 @@ App(createReactApp(AppComponent, React, ReactDOM, appConfig))
 export function createWxPageEntry(pageOption) {
     const wechatPageConfigCode = JSON.stringify(pageOption.config);
     const pageComponentImport = createPageComponentImport(pageOption.path);
-    return `import { createPageConfig } from 'vite-plugin-taro/shim/wx'
+    return `import { createPageConfig } from ${JSON.stringify(wxShimImportPath)}
 import PageComponent from '${pageComponentImport}'
 
 const pageConfig = ${wechatPageConfigCode}
@@ -195,7 +195,7 @@ Page(taroPageConfig)
  * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-webpack5-runner/src/template/comp.ts#L1-L4
  */
 export function createWxCompEntry() {
-    return `import { createRecursiveComponentConfig } from 'vite-plugin-taro/shim/wx'
+    return `import { createRecursiveComponentConfig } from ${JSON.stringify(wxShimImportPath)}
 
 Component(createRecursiveComponentConfig())
 `;

package/dist/vite/virtual-modules.js

@@ -0,0 +1,13 @@
+import path from 'node:path';
+import { nodeRequire } from './constants.js';
+export const virtualTaroApiId = 'virtual:taro/api';
+export const virtualTaroComponentsId = 'virtual:taro/components';
+const packageRoot = path.dirname(nodeRequire.resolve('vite-plugin-taro/package.json'));
+const virtualTaroApiResolvedId = path.join(packageRoot, 'dist/virtual/api.js');
+const virtualTaroComponentsResolvedId = path.join(packageRoot, 'dist/virtual/components.js');
+export function resolvePublicVirtualModuleId(id) {
+    if (id === virtualTaroApiId)
+        return virtualTaroApiResolvedId;
+    if (id === virtualTaroComponentsId)
+        return virtualTaroComponentsResolvedId;
+}