vite-plugin-taro 0.1.2 → 0.1.4

package/README.en.md

@@ -17,7 +17,7 @@ Live demo: <https://sep2.github.io/vite-plugin-taro>. See [Sample app](https://g
 - **Battle-tested Taro foundation** Use the full set of Taro APIs and components instead of reinventing cross-platform primitives.
 - **Tailwind ready** Built-in Tailwind CSS v4 support for both WeChat Mini Program and H5 styles.
 - **Conditional compilation** Use Taro-style `#ifdef` / `#ifndef` / `#if` blocks to split code and styles by `wx` / `h5` target.
-- **Type-friendly** Import Taro capabilities consistently through `virtual:taro/api` and `virtual:taro/components`, with TypeScript type support.
+- **Type-friendly** The project supports TypeScript all the way.
 - **WeChat Skyline** Support WeChat Mini Program output with Skyline rendering mode.
 
 ## Quick start
@@ -28,11 +28,11 @@ Use `create-vite-taro` for new apps. It generates a Vite 8 + React 19 + Taro pro
 
 ```sh
 # Create a new app from the default template
-pnpm create vite-taro my-app
+npm create vite-taro@latest my-app
 
 # Enter the project and install dependencies
 cd my-app
-pnpm install
+npm install
 ```
 
 ### 2. Configure WeChat App ID
@@ -43,18 +43,18 @@ The template creates `.env.local`. Set `VITE_PLUGIN_TARO_WECHAT_APP_ID` to your
 
 ```sh
 # WeChat Mini Program: rebuild dist/wx in watch mode
-pnpm dev:wx
+npm run dev:wx
 
 # Then open dist/wx in WeChat DevTools
 
 # H5: start the Vite dev server
-pnpm dev:h5
+npm run dev:h5
 
 # Then open the standard Vite dev URL in your browser
 # http://localhost:5173
 ```
 
-You can keep `pnpm dev:wx` and `pnpm dev:h5` running at the same time in separate terminals.
+You can keep `npm run dev:wx` and `npm run dev:h5` running at the same time in separate terminals.
 
 Note: Because of WeChat DevTools and Mini Program runtime limitations, hot reload/fast rebuilds for the WeChat target may not always apply cleanly. For day-to-day iteration, prefer the H5 Vite dev server for fast feedback, and periodically verify the Mini Program result in WeChat DevTools.
 
@@ -62,33 +62,50 @@ Note: Because of WeChat DevTools and Mini Program runtime limitations, hot reloa
 
 ```sh
 # Production WeChat Mini Program output
-pnpm build:wx
+npm run build:wx
 
 # Production H5 output
-pnpm build:h5
+npm run build:h5
 
 # Preview the built H5 app
-pnpm preview:h5
+npm run preview:h5
 
 # Typecheck with tsgo
-pnpm typecheck
+npm run typecheck
 ```
 
-For existing apps or custom project layouts, follow the manual setup below.
+### 5. Use Taro virtual modules
+
+Use these imports in app code:
+
+```tsx
+import Taro from 'virtual:taro/api'
+import { Text, View } from 'virtual:taro/components'
+```
+
+| Import | Use |
+| --- | --- |
+| `virtual:taro/components` | Taro React components such as `View`, `Text`, `Button`, `Image`, and `ScrollView`. |
+| `virtual:taro/api` | Taro APIs and hooks such as `Taro.navigateTo`, `Taro.getWindowInfo`, and `Taro.useLaunch`. |
+
+Usage is the same as Taro itself; see the [Taro website](https://docs.taro.zone) for component and API details.
+
+You no longer need to install `@tarojs/*` packages; application code should not import from `@tarojs/*`.
+
 
 ## Manual setup for existing apps
 
 For existing apps or custom project layouts, follow the steps below to wire the plugin manually. First, install the plugin:
 
 ```sh
-pnpm add -D vite-plugin-taro
+npm install -D vite-plugin-taro
 ```
 
 Your app must also provide Vite 8, React 19, React DOM 19, a TypeScript checker, and Node/React type packages. If your app does not already have them, install the missing packages:
 
 ```sh
-pnpm add react react-dom
-pnpm add -D vite @typescript/native-preview @types/node @types/react @types/react-dom
+npm install react react-dom
+npm install -D vite @typescript/native-preview @types/node @types/react @types/react-dom
 ```
 
 You should NOT have direct dependencies on `@tarojs/*` packages anymore. Remove them if you have.
@@ -238,15 +255,6 @@ export default function IndexPage() {
 }
 ```
 
-Use these imports in app code:
-
-| Import | Use |
-| --- | --- |
-| `virtual:taro/components` | Taro React components such as `View`, `Text`, `Button`, `Image`, and `ScrollView`. |
-| `virtual:taro/api` | Taro APIs and hooks such as `Taro.navigateTo`, `Taro.getWindowInfo`, and `Taro.useLaunch`. |
-
-Do not import `@tarojs/*` packages directly in application code. Direct `@tarojs/*` usage is forbidden and unsupported by this plugin because it can bypass target-specific runtime aliases and H5 API transforms. Use `virtual:taro/api` and `virtual:taro/components` only.
-
 ### 5. Add the H5 HTML shell
 
 For H5, keep a normal Vite `index.html` with an `#app` mount node. The plugin injects the generated Taro H5 entry automatically, so you do not need a normal Vite `src/main.tsx` script.
@@ -287,12 +295,12 @@ On Windows shells, use `cross-env`.
 ### 7. Run each target
 
 ```sh
-pnpm dev:wx       # Rebuild dist/wx in watch mode
-pnpm dev:h5       # Start the H5 dev server
-pnpm build:wx     # Build dist/wx
-pnpm build:h5     # Build dist/h5
-pnpm preview:h5   # Preview dist/h5
-pnpm typecheck    # Typecheck with tsgo
+npm run dev:wx       # Rebuild dist/wx in watch mode
+npm run dev:h5       # Start the H5 dev server
+npm run build:wx     # Build dist/wx
+npm run build:h5     # Build dist/h5
+npm run preview:h5   # Preview dist/h5
+npm run typecheck    # Typecheck with tsgo
 ```
 
 Open the generated `dist/wx` directory in WeChat DevTools.
@@ -499,7 +507,7 @@ Common scripts:
 | Problem | Check |
 | --- | --- |
 | `VITE_PLUGIN_TARO_TARGET must be "wx" or "h5"` | Set the target environment variable in your script or `.env` file. |
-| `pnpm install` says dependency build scripts were ignored | Run `pnpm approve-builds`, approve the requested dependency build scripts, then rerun `pnpm install` if needed. |
+| `pnpm install` says dependency build scripts were ignored | Run `pnpm approve-builds` and approve the requested dependency build scripts. |
 | A page cannot be resolved | Confirm that `pages[].path` has a matching `src/${path}.tsx` file. |
 | WeChat DevTools cannot open the app | Open the generated `dist/wx` folder and check `projectConfigJson.appid`. |
 | H5 shows a blank page | Keep `<div id="app"></div>` in `index.html`, register the plugin, and avoid adding a separate default Vite `main.tsx` entry. |

package/README.md

@@ -17,7 +17,7 @@
 - **依托成熟 Taro 能力** 复用久经实战检验的 Taro API 和组件，完整使用 Taro 跨端能力。
 - **Tailwind 就绪** 内置 Tailwind CSS v4 支持，微信小程序与 H5 样式开箱即用。
 - **条件编译** 支持 Taro 风格 `#ifdef` / `#ifndef` / `#if`，可按 `wx` / `h5` 裁剪代码和样式。
-- **类型友好** 通过 `virtual:taro/api` 和 `virtual:taro/components` 统一导入 Taro 能力，并提供 TypeScript 类型支持。
+- **类型友好** 项目全链路支持 TypeScript。
 - **微信 Skyline** 支持微信小程序 Skyline 渲染模式输出。
 
 ## 快速开始
@@ -28,11 +28,11 @@
 
 ```sh
 # 使用默认模板创建新应用
-pnpm create vite-taro my-app
+npm create vite-taro@latest my-app
 
 # 进入项目并安装依赖
 cd my-app
-pnpm install
+npm install
 ```
 
 ### 2. 配置微信 App ID
@@ -43,18 +43,18 @@ pnpm install
 
 ```sh
 # 微信小程序：以 watch 模式重新构建 dist/wx
-pnpm dev:wx
+npm run dev:wx
 
 # 然后在微信开发者工具中打开 dist/wx
 
 # H5：启动 Vite 开发服务器
-pnpm dev:h5
+npm run dev:h5
 
 # 然后在浏览器中打开标准 Vite 地址
 # http://localhost:5173
 ```
 
-你可以在两个终端中同时运行 `pnpm dev:wx` 和 `pnpm dev:h5`。
+你可以在两个终端中同时运行 `npm run dev:wx` 和 `npm run dev:h5`。
 
 提示：受微信限制，开发者工具热重载有时不会完整生效。建议日常优先使用 H5 的 Vite 热更新快速调试，并定期在微信开发者工具中验证小程序端效果。
 
@@ -62,33 +62,50 @@ pnpm dev:h5
 
 ```sh
 # 生产微信小程序产物
-pnpm build:wx
+npm run build:wx
 
 # 生产 H5 产物
-pnpm build:h5
+npm run build:h5
 
 # 预览构建后的 H5 应用
-pnpm preview:h5
+npm run preview:h5
 
 # 使用 tsgo 进行类型检查
-pnpm typecheck
+npm run typecheck
 ```
 
-已有应用或自定义项目结构，请继续阅读下面的手动接入步骤。
+### 5. 使用 Taro 虚拟模块
+
+应用代码请使用这些导入：
+
+```tsx
+import Taro from 'virtual:taro/api'
+import { Text, View } from 'virtual:taro/components'
+```
+
+| 导入 | 用途 |
+| --- | --- |
+| `virtual:taro/components` | Taro React 组件，例如 `View`、`Text`、`Button`、`Image` 和 `ScrollView`。 |
+| `virtual:taro/api` | Taro API 和 hooks，例如 `Taro.navigateTo`、`Taro.getWindowInfo` 和 `Taro.useLaunch`。 |
+
+用法与 Taro 本身一致；组件和 API 的具体用法请参考 [Taro 官网](https://docs.taro.zone)。
+
+你不再需要安装 `@tarojs/*` 包；应用代码也不要从 `@tarojs/*` 导入。
+
 
 ## 手动接入已有应用
 
 已有应用或自定义项目结构，可以按下面的步骤手动接入插件。先安装插件：
 
 ```sh
-pnpm add -D vite-plugin-taro
+npm install -D vite-plugin-taro
 ```
 
 你的应用还必须提供 Vite 8、React 19、React DOM 19、TypeScript 检查器，以及 Node/React 类型包。如果应用尚未安装它们，请安装缺失的包：
 
 ```sh
-pnpm add react react-dom
-pnpm add -D vite @typescript/native-preview @types/node @types/react @types/react-dom
+npm install react react-dom
+npm install -D vite @typescript/native-preview @types/node @types/react @types/react-dom
 ```
 
 你不应再直接依赖任何 `@tarojs/*` 包。如果已经依赖，请将它们移除。
@@ -238,15 +255,6 @@ export default function IndexPage() {
 }
 ```
 
-应用代码请使用这些导入：
-
-| 导入 | 用途 |
-| --- | --- |
-| `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 外壳
 
 对于 H5，请保留一个普通的 Vite `index.html`，并包含 `#app` 挂载节点。插件会自动注入生成的 Taro H5 入口，因此你不需要普通 Vite 的 `src/main.tsx` 脚本。
@@ -287,12 +295,12 @@ export default function IndexPage() {
 ### 7. 运行每个目标
 
 ```sh
-pnpm dev:wx       # 以 watch 模式重新构建 dist/wx
-pnpm dev:h5       # 启动 H5 开发服务器
-pnpm build:wx     # 构建 dist/wx
-pnpm build:h5     # 构建 dist/h5
-pnpm preview:h5   # 预览 dist/h5
-pnpm typecheck    # 使用 tsgo 进行类型检查
+npm run dev:wx       # 以 watch 模式重新构建 dist/wx
+npm run dev:h5       # 启动 H5 开发服务器
+npm run build:wx     # 构建 dist/wx
+npm run build:h5     # 构建 dist/h5
+npm run preview:h5   # 预览 dist/h5
+npm run typecheck    # 使用 tsgo 进行类型检查
 ```
 
 在微信开发者工具中打开生成的 `dist/wx` 目录。
@@ -499,7 +507,7 @@ pnpm typecheck
 | 问题 | 检查项 |
 | --- | --- |
 | `VITE_PLUGIN_TARO_TARGET must be "wx" or "h5"` | 在脚本或 `.env` 文件中设置目标环境变量。 |
-| `pnpm install` 提示忽略了依赖构建脚本 | 运行 `pnpm approve-builds`，按提示批准需要构建的依赖；如有需要再重新执行 `pnpm install`。 |
+| `pnpm install` 提示忽略了依赖构建脚本 | 运行 `pnpm approve-builds`，按提示批准需要构建的依赖。 |
 | 页面无法解析 | 确认 `pages[].path` 有匹配的 `src/${path}.tsx` 文件。 |
 | 微信开发者工具无法打开应用 | 打开生成的 `dist/wx` 文件夹，并检查 `projectConfigJson.appid`。 |
 | H5 显示空白页 | 确保 `index.html` 中保留 `<div id="app"></div>`，已注册插件，并避免添加单独的默认 Vite `main.tsx` 入口。 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-taro",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "author": "sep2",
   "description": "Vite 8 plugin for building one React/Taro codebase for WeChat Mini Program and H5 targets.",
   "type": "module",
@@ -64,8 +64,8 @@
     "babel-plugin-transform-taroapi": "^4.2.0",
     "tailwindcss": "^4.3.1",
     "weapp-tailwindcss": "^5.0.13",
-    "@tarojs/react": "npm:vite-plugin-taro-react@0.1.2",
-    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.1.2"
+    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.1.4",
+    "@tarojs/react": "npm:vite-plugin-taro-react@0.1.4"
   },
   "peerDependencies": {
     "react": "^19.0.0",