vite-plugin-taro 0.1.1 → 0.1.2

package/README.en.md

@@ -7,37 +7,93 @@
 
 Build WeChat Mini Apps with the latest standards-based frontend stack: Vite 8, React 19, and Tailwind CSS v4.
 
-`vite-plugin-taro` is for applications that want Taro's cross-platform React components and APIs, but prefer Vite instead of Taro webpack. The plugin generates app/page entries, target runtime aliases, H5 router bootstrap, WeChat companion files, Tailwind processing, and conditional compilation for you.
+`vite-plugin-taro` is for applications that want Taro's cross-platform React components and APIs, but prefer Vite instead of Taro webpack. The plugin generates app/page entries, target runtime aliases, WeChat companion files, H5 router bootstrap, Tailwind processing, and conditional compilation for you.
 
 Live demo: <https://sep2.github.io/vite-plugin-taro>. See [Sample app](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius/README.en.md) how to run it locally.
 
-- **One codebase, two targets** Build H5 and WeChat Mini Program outputs from shared React/Taro pages.
+- **One codebase, two targets** Build WeChat Mini Program and H5 outputs from shared React/Taro pages.
 - **Native Vite builds** Use standard Vite 8 config instead of legacy webpack configuration, with support for all Vite plugins.
-- **Hot reload** Both H5 and WeChat Mini Program support dev-mode watch, with Vite 8 HMR/rebuilds for fast feedback.
+- **Hot reload** Both WeChat Mini Program and H5 support dev-mode watch, with Vite 8 HMR/rebuilds for fast feedback.
 - **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 H5 and WeChat Mini Program styles.
-- **Conditional compilation** Use Taro-style `#ifdef` / `#ifndef` / `#if` blocks to split code and styles by `h5` / `wx` target.
+- **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.
 - **WeChat Skyline** Support WeChat Mini Program output with Skyline rendering mode.
 
-## Install
+## Quick start
+
+Use `create-vite-taro` for new apps. It generates a Vite 8 + React 19 + Taro project with WeChat Mini Program and H5 scripts already wired.
+
+### 1. Create and install
+
+```sh
+# Create a new app from the default template
+pnpm create vite-taro my-app
+
+# Enter the project and install dependencies
+cd my-app
+pnpm install
+```
+
+### 2. Configure WeChat App ID
+
+The template creates `.env.local`. Set `VITE_PLUGIN_TARO_WECHAT_APP_ID` to your WeChat App ID.
+
+### 3. Run in development
+
+```sh
+# WeChat Mini Program: rebuild dist/wx in watch mode
+pnpm dev:wx
+
+# Then open dist/wx in WeChat DevTools
+
+# H5: start the Vite dev server
+pnpm 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.
+
+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.
+
+### 4. Build, preview, and typecheck
+
+```sh
+# Production WeChat Mini Program output
+pnpm build:wx
+
+# Production H5 output
+pnpm build:h5
+
+# Preview the built H5 app
+pnpm preview:h5
+
+# Typecheck with tsgo
+pnpm typecheck
+```
+
+For existing apps or custom project layouts, follow the manual setup below.
+
+## 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
 ```
 
-Your app must also provide Vite 8, React 19, React DOM 19, TypeScript, and React type packages. If your app does not already have them, install the missing packages:
+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 @types/react @types/react-dom
+pnpm add -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.
 
-## Quick start
-
-The examples below create this source shape:
+The steps below create this source shape:
 
 ```text
 my-app/
@@ -82,8 +138,8 @@ 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".`)
+    if (target === 'wx' || target === 'h5') return target
+    throw new Error(`${targetEnvName} must be "wx" or "h5".`)
 }
 
 export default defineConfig(({ mode }) => {
@@ -128,7 +184,7 @@ export default defineConfig(({ mode }) => {
 
 Important conventions:
 
-- `target` must be `h5` or `wx` for each Vite run.
+- `target` must be `wx` or `h5` for each Vite run.
 - `app` is the root React app component module. It should default-export the app component.
 - Every `pages[].path` maps to a file at `src/${path}.tsx`. For example, `pages/index/index` requires `src/pages/index/index.tsx`.
 - `appJson.pages` is generated from `pages`; any `pages` field you put in `appJson` is overwritten.
@@ -154,15 +210,15 @@ function App({ children }: PropsWithChildren) {
 export default App
 ```
 
-Import global styles from the app component. They are included in H5 output and collected into `app.wxss` for WeChat builds.
+Import global styles from the app component. They are collected into `app.wxss` for WeChat builds and included in H5 output.
 
 ### 4. Create a page component
 
 `src/pages/index/index.tsx` is the React component for `pages/index/index`.
 
 ```tsx
-import { Button, Text, View } from 'virtual:taro/components'
 import Taro from 'virtual:taro/api'
+import { Button, Text, View } from 'virtual:taro/components'
 
 export default function IndexPage() {
     const windowInfo = Taro.getWindowInfo()
@@ -211,13 +267,17 @@ For H5, keep a normal Vite `index.html` with an `#app` mount node. The plugin in
 
 ### 6. Add scripts
 
+Use the same scripts generated by `create-vite-taro`:
+
 ```json
 {
     "scripts": {
+        "dev:wx": "NODE_ENV=development VITE_PLUGIN_TARO_TARGET=wx vite build --watch",
         "dev:h5": "NODE_ENV=development VITE_PLUGIN_TARO_TARGET=h5 vite",
+        "build:wx": "NODE_ENV=production VITE_PLUGIN_TARO_TARGET=wx vite build",
         "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"
+        "preview:h5": "NODE_ENV=production VITE_PLUGIN_TARO_TARGET=h5 vite preview --outDir dist/h5",
+        "typecheck": "tsgo -b"
     }
 }
 ```
@@ -227,18 +287,20 @@ 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:h5     # Build dist/h5
 pnpm build:wx     # Build dist/wx
-pnpm dev:wx       # Rebuild dist/wx in watch mode
+pnpm build:h5     # Build dist/h5
+pnpm preview:h5   # Preview dist/h5
+pnpm typecheck    # Typecheck with tsgo
 ```
 
 Open the generated `dist/wx` directory in WeChat DevTools.
 
-| Target | Meaning                                    | output dirs |
-| --- |--------------------------------------------|-------------|
-| `h5` | H5 production output.                      | `dist/h5`   |
-| `wx` | WeChat Mini Program in both dev/prod mode. | `dist/wx`   |
+| Target | Meaning | Output dir |
+| --- | --- | --- |
+| `wx` | WeChat Mini Program in both dev/prod mode. | `dist/wx` |
+| `h5` | H5 production output. | `dist/h5` |
 
 ## Options
 
@@ -262,7 +324,7 @@ type VitePluginTaroOptions = {
 
 | Option | Description |
 | --- | --- |
-| `target` | Active target for this Vite invocation. Use `h5` for Web and `wx` for WeChat Mini Program. |
+| `target` | Active target for this Vite invocation. Use `wx` for WeChat Mini Program and `h5` for Web. |
 | `app` | Source file that default-exports the root React app component, for example `src/app.ts` or `src/app.tsx`. |
 | `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`. |
@@ -285,7 +347,7 @@ For Tailwind CSS v4, import Tailwind from a global CSS file such as `src/app.css
 @source "./";
 ```
 
-The plugin registers `@tailwindcss/vite` for `h5` builds and `weapp-tailwindcss` for `wx` builds. For `wx`, CSS emitted by Vite is collected into `app.wxss`, and page `.wxss` companion files are emitted for each page.
+The plugin registers `weapp-tailwindcss` for `wx` builds and `@tailwindcss/vite` for `h5` builds. For `wx`, CSS emitted by Vite is collected into `app.wxss`, and page `.wxss` companion files are emitted for each page.
 
 ## Conditional compilation
 
@@ -300,23 +362,19 @@ console.log('WeChat only')
 console.log('H5 only')
 // #endif
 
-// #if h5 && !wx
-console.log('H5 expression')
-// #elif wx
+// #if wx && !h5
 console.log('WeChat expression')
+// #elif h5
+console.log('H5 expression')
 // #else
 console.log('fallback')
 // #endif
 ```
 
-Supported directives are `#ifdef`, `#ifndef`, `#if`, `#elif`, `#else`, and `#endif`. Conditions use the plugin target tokens `h5` and `wx`; `#if` expressions support `!`, `&&`, and `||`.
+Supported directives are `#ifdef`, `#ifndef`, `#if`, `#elif`, `#else`, and `#endif`. Conditions use the plugin target tokens `wx` and `h5`; `#if` expressions support `!`, `&&`, and `||`.
 
 ## Output by target
 
-### H5
-
-For `target: 'h5'`, the plugin injects a generated module into `index.html`, imports Taro's H5 component styles, builds route records from `pages`, and mounts the app with Taro's hash-history router. Routes use the page paths from your config, for example `#/pages/index/index`.
-
 ### WeChat Mini Program
 
 For `target: 'wx'`, the plugin configures Vite to emit WeChat-compatible CommonJS chunks and Mini Program companion files.
@@ -340,6 +398,10 @@ dist/wx/
 
 Open `dist/wx` with WeChat DevTools; do not open the source project directory.
 
+### H5
+
+For `target: 'h5'`, the plugin injects a generated module into `index.html`, imports Taro's H5 component styles, builds route records from `pages`, and mounts the app with Taro's hash-history router. Routes use the page paths from your config, for example `#/pages/index/index`.
+
 ## Migrating from Taro
 
 You can keep most React page components, business logic, assets, and styles, but the build entry moves from Taro CLI config to Vite config.
@@ -349,7 +411,7 @@ Migration checklist:
 1. Install `vite-plugin-taro` and create `vite.config.ts` with `vitePluginTaro(...)`.
 2. Move app config and page config into the plugin options. The plugin does not read Taro CLI files such as `config/index.ts`, `app.config.ts`, or page `config.ts` files.
 3. Register every page in `pages`. Each page path must match `src/${path}.tsx`.
-4. Replace Taro scripts with Vite scripts that set `VITE_PLUGIN_TARO_TARGET=h5` or `VITE_PLUGIN_TARO_TARGET=wx`.
+4. Replace Taro scripts with Vite scripts that set `VITE_PLUGIN_TARO_TARGET=wx` or `VITE_PLUGIN_TARO_TARGET=h5`.
 5. For H5, add a normal Vite `index.html` with `<div id="app"></div>` and no separate `src/main.tsx` entry.
 6. Replace application imports from `@tarojs/*` with the plugin virtual modules.
 
@@ -367,11 +429,11 @@ import Taro from 'virtual:taro/api'
 import { Text, View } from 'virtual:taro/components'
 ```
 
-Direct `@tarojs/*` imports in application code are forbidden. Let the plugin own Taro runtime resolution so H5 and WeChat builds receive the correct target-specific aliases.
+Direct `@tarojs/*` imports in application code are forbidden. Let the plugin own Taro runtime resolution so WeChat and H5 builds receive the correct target-specific aliases.
 
 ## Sample app
 
-The sample app lives in [`packages/loan-genius`](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius). It demonstrates the page convention, target selection, H5 routing, Tailwind styling, and WeChat output.
+The sample app lives in [`packages/loan-genius`](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius). It demonstrates the page convention, target selection, WeChat output, H5 routing, and Tailwind styling.
 
 ```sh
 git clone https://github.com/sep2/vite-plugin-taro.git
@@ -385,23 +447,22 @@ pnpm prepare:taro
 # Build the plugin for sample app to use
 pnpm build:plugin
 
-# Run the sample app in H5 in Dev mode
-pnpm dev:sample:h5
-
-# Build the sample app to H5 output and preview it
-pnpm build:sample:h5
-pnpm preview:sample:h5
-
 # Run the sample app in WeChat
 pnpm dev:sample:wx
 
 # Build the sample app to WeChat output
 pnpm build:sample:wx
+
+# Run the sample app in H5 dev mode
+pnpm dev:sample:h5
+
+# Build the sample app to H5 output and preview it
+pnpm build:sample:h5
+pnpm preview:sample:h5
 ```
 
 Open `packages/loan-genius/dist/wx` with WeChat DevTools to test the Mini Program output.
 
-
 ## Develop this repository
 
 ```sh
@@ -420,30 +481,30 @@ Common scripts:
 | `pnpm typecheck` | Typecheck the plugin and sample app with `tsgo`. |
 | `pnpm lint` | Run Biome checks. |
 | `pnpm format` | Apply Biome formatting. |
-| `pnpm dev:sample:h5` | Start the sample H5 app in Vite dev mode. Build the plugin first. |
 | `pnpm dev:sample:wx` | Build the sample WeChat Mini Program in watch mode. Build the plugin first. |
-| `pnpm build:sample:h5` | Build the sample H5 app to `packages/loan-genius/dist/h5`. |
+| `pnpm dev:sample:h5` | Start the sample H5 app in Vite dev mode. Build the plugin first. |
+| `pnpm build:sample:wx` | Build the WeChat Mini Program sample to `packages/loan-genius/dist/wx`. |
+| `pnpm build:sample:h5` | Build the H5 sample app to `packages/loan-genius/dist/h5`. |
 | `pnpm preview:sample:h5` | Preview the built H5 sample. |
-| `pnpm build:sample:wx` | Build the sample WeChat Mini Program to `packages/loan-genius/dist/wx`. |
 | `pnpm publish:dry` | Dry-run package validation and publishing. |
 | `pnpm publish:all` | Publish the public packages in dependency order. |
 
 ## Limitations
 
-- Only `h5` and `wx` targets are generated today.
+- Only `wx` and `h5` targets are generated today.
 - Application code must not import `@tarojs/*` packages directly.
 
-
 ## Troubleshooting
 
 | Problem | Check |
 | --- | --- |
-| `VITE_PLUGIN_TARO_TARGET must be "h5" or "wx"` | Set the target environment variable in your script or `.env` file. |
+| `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. |
 | 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. |
 | Taro APIs are missing or behave differently | Remove direct `@tarojs/*` imports from application code and import Taro from `virtual:taro/api`. |
 | Components render without expected styles on H5 | Import components from `virtual:taro/components` and keep the plugin enabled for the `h5` target. |
-| WeChat DevTools cannot open the app | Open the generated `dist/wx` folder and check `projectConfigJson.appid`. |
 | Tailwind classes do not appear | Ensure your global CSS imports Tailwind and includes an `@source` path that covers your source files. |
 
 ## Release workflow
@@ -460,7 +521,6 @@ Publish all public packages in the required order:
 pnpm publish:all
 ```
 
-
 ## License
 
 MIT

package/README.md

@@ -7,37 +7,93 @@
 
 使用最新标准化前端技术栈 Vite 8、React 19 和 Tailwind CSS v4 构建微信小程序。
 
-`vite-plugin-taro` 适用于希望使用 Taro 跨平台 React 组件和 API，但更偏好 Vite 而非 Taro webpack 的应用。插件会为你生成应用/页面入口、目标运行时别名、H5 路由启动代码、微信端配套文件、Tailwind 处理，以及条件编译。
+`vite-plugin-taro` 适用于希望使用 Taro 跨平台 React 组件和 API，但更偏好 Vite 而非 Taro webpack 的应用。插件会为你生成应用/页面入口、目标运行时别名、微信端配套文件、H5 路由启动代码、Tailwind 处理，以及条件编译。
 
 在线演示：<https://sep2.github.io/vite-plugin-taro>。如何在本地运行，请参见[示例应用](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius/README.md)。
 
-- **一套代码，双端输出** 同一套 React/Taro 页面构建 H5 与微信小程序。
+- **一套代码，双端输出** 同一套 React/Taro 页面构建微信小程序与 H5。
 - **原生 Vite 构建** 使用标准 Vite 8 配置，无需维护老旧的 webpack 配置，并支持所有 Vite 插件。
-- **热更新** H5 与微信小程序都支持开发模式 watch，基于 Vite 8 热更新/快速重建即时预览。
+- **热更新** 微信小程序与 H5 都支持开发模式 watch，基于 Vite 8 热更新/快速重建即时预览。
 - **依托成熟 Taro 能力** 复用久经实战检验的 Taro API 和组件，完整使用 Taro 跨端能力。
-- **Tailwind 就绪** 内置 Tailwind CSS v4 支持，H5 与微信小程序样式开箱即用。
-- **条件编译** 支持 Taro 风格 `#ifdef` / `#ifndef` / `#if`，可按 `h5` / `wx` 裁剪代码和样式。
+- **Tailwind 就绪** 内置 Tailwind CSS v4 支持，微信小程序与 H5 样式开箱即用。
+- **条件编译** 支持 Taro 风格 `#ifdef` / `#ifndef` / `#if`，可按 `wx` / `h5` 裁剪代码和样式。
 - **类型友好** 通过 `virtual:taro/api` 和 `virtual:taro/components` 统一导入 Taro 能力，并提供 TypeScript 类型支持。
 - **微信 Skyline** 支持微信小程序 Skyline 渲染模式输出。
 
-## 安装
+## 快速开始
+
+新应用推荐使用 `create-vite-taro`。它会生成已接好微信小程序与 H5 脚本的 Vite 8 + React 19 + Taro 项目。
+
+### 1. 创建并安装
+
+```sh
+# 使用默认模板创建新应用
+pnpm create vite-taro my-app
+
+# 进入项目并安装依赖
+cd my-app
+pnpm install
+```
+
+### 2. 配置微信 App ID
+
+模板会创建 `.env.local`。请将 `VITE_PLUGIN_TARO_WECHAT_APP_ID` 设置为你的微信 App ID。
+
+### 3. 开发模式运行
+
+```sh
+# 微信小程序：以 watch 模式重新构建 dist/wx
+pnpm dev:wx
+
+# 然后在微信开发者工具中打开 dist/wx
+
+# H5：启动 Vite 开发服务器
+pnpm dev:h5
+
+# 然后在浏览器中打开标准 Vite 地址
+# http://localhost:5173
+```
+
+你可以在两个终端中同时运行 `pnpm dev:wx` 和 `pnpm dev:h5`。
+
+提示：受微信限制，开发者工具热重载有时不会完整生效。建议日常优先使用 H5 的 Vite 热更新快速调试，并定期在微信开发者工具中验证小程序端效果。
+
+### 4. 构建、预览和类型检查
+
+```sh
+# 生产微信小程序产物
+pnpm build:wx
+
+# 生产 H5 产物
+pnpm build:h5
+
+# 预览构建后的 H5 应用
+pnpm preview:h5
+
+# 使用 tsgo 进行类型检查
+pnpm typecheck
+```
+
+已有应用或自定义项目结构，请继续阅读下面的手动接入步骤。
+
+## 手动接入已有应用
+
+已有应用或自定义项目结构，可以按下面的步骤手动接入插件。先安装插件：
 
 ```sh
 pnpm add -D vite-plugin-taro
 ```
 
-你的应用还必须提供 Vite 8、React 19、React DOM 19、TypeScript 以及 React 类型包。如果应用尚未安装它们，请安装缺失的包：
+你的应用还必须提供 Vite 8、React 19、React DOM 19、TypeScript 检查器，以及 Node/React 类型包。如果应用尚未安装它们，请安装缺失的包：
 
 ```sh
 pnpm add react react-dom
-pnpm add -D vite typescript @types/react @types/react-dom
+pnpm add -D vite @typescript/native-preview @types/node @types/react @types/react-dom
 ```
 
 你不应再直接依赖任何 `@tarojs/*` 包。如果已经依赖，请将它们移除。
 
-## 快速开始
-
-下面的示例会创建如下源码结构：
+下面的步骤会创建如下源码结构：
 
 ```text
 my-app/
@@ -82,8 +138,8 @@ 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".`)
+    if (target === 'wx' || target === 'h5') return target
+    throw new Error(`${targetEnvName} must be "wx" or "h5".`)
 }
 
 export default defineConfig(({ mode }) => {
@@ -128,15 +184,15 @@ export default defineConfig(({ mode }) => {
 
 重要约定：
 
-- 每次 Vite 运行时，`target` 必须是 `h5` 或 `wx`。
-- `app` 是根 React 应用组件模块。它应默认导出应用组件。
-- 每个 `pages[].path` 都映射到 `src/${path}.tsx` 文件。例如，`pages/index/index` 要求存在 `src/pages/index/index.tsx`。
-- `appJson.pages` 会根据 `pages` 生成；你在 `appJson` 中传入的任何 `pages` 字段都会被覆盖。
+- 每次 Vite 运行时，`target` 必须是 `wx` 或 `h5`。
+- `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` 接收当前页面。
+`src/app.ts` 是共享应用包装组件。它会通过 `children` 接收当前页面。
 
 ```tsx
 import Taro from 'virtual:taro/api'
@@ -154,15 +210,15 @@ function App({ children }: PropsWithChildren) {
 export default App
 ```
 
-从应用组件中导入全局样式。它们会包含在 H5 输出中，并在微信构建中收集到 `app.wxss`。
+请在应用组件中导入全局样式。微信构建会将它们收集到 `app.wxss`，H5 输出也会包含它们。
 
 ### 4. 创建页面组件
 
-`src/pages/index/index.tsx` 是 `pages/index/index` 对应的 React 组件。
+`src/pages/index/index.tsx` 是 `pages/index/index` 对应的 React 页面组件。
 
 ```tsx
-import { Button, Text, View } from 'virtual:taro/components'
 import Taro from 'virtual:taro/api'
+import { Button, Text, View } from 'virtual:taro/components'
 
 export default function IndexPage() {
     const windowInfo = Taro.getWindowInfo()
@@ -182,7 +238,7 @@ export default function IndexPage() {
 }
 ```
 
-在应用代码中使用这些导入：
+应用代码请使用这些导入：
 
 | 导入 | 用途 |
 | --- | --- |
@@ -211,13 +267,17 @@ export default function IndexPage() {
 
 ### 6. 添加脚本
 
+使用与 `create-vite-taro` 生成项目一致的脚本：
+
 ```json
 {
     "scripts": {
+        "dev:wx": "NODE_ENV=development VITE_PLUGIN_TARO_TARGET=wx vite build --watch",
         "dev:h5": "NODE_ENV=development VITE_PLUGIN_TARO_TARGET=h5 vite",
+        "build:wx": "NODE_ENV=production VITE_PLUGIN_TARO_TARGET=wx vite build",
         "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"
+        "preview:h5": "NODE_ENV=production VITE_PLUGIN_TARO_TARGET=h5 vite preview --outDir dist/h5",
+        "typecheck": "tsgo -b"
     }
 }
 ```
@@ -227,18 +287,20 @@ export default function IndexPage() {
 ### 7. 运行每个目标
 
 ```sh
+pnpm dev:wx       # 以 watch 模式重新构建 dist/wx
 pnpm dev:h5       # 启动 H5 开发服务器
-pnpm build:h5     # 构建 dist/h5
 pnpm build:wx     # 构建 dist/wx
-pnpm dev:wx       # 以 watch 模式重新构建 dist/wx
+pnpm build:h5     # 构建 dist/h5
+pnpm preview:h5   # 预览 dist/h5
+pnpm typecheck    # 使用 tsgo 进行类型检查
 ```
 
 在微信开发者工具中打开生成的 `dist/wx` 目录。
 
 | 目标 | 含义 | 输出目录 |
 | --- | --- | --- |
-| `h5` | H5 生产输出。 | `dist/h5` |
 | `wx` | 开发/生产模式下的微信小程序。 | `dist/wx` |
+| `h5` | H5 生产输出。 | `dist/h5` |
 
 ## 选项
 
@@ -262,12 +324,12 @@ type VitePluginTaroOptions = {
 
 | 选项 | 描述 |
 | --- | --- |
-| `target` | 本次 Vite 调用的活动目标。Web 使用 `h5`，微信小程序使用 `wx`。 |
+| `target` | 本次 Vite 调用的活动目标。微信小程序使用 `wx`，Web 使用 `h5`。 |
 | `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` 字段。 |
+| `appJson` | 基础应用配置。插件会用 `options.pages` 覆盖其中的 `pages` 字段。 |
 | `projectConfigJson` | `wx` 构建时输出的微信 `project.config.json` 内容。即使当前目标是 `h5`，选项类型也要求提供它。 |
 | `sitemapJson` | `wx` 构建时输出的微信 `sitemap.json` 内容。即使当前目标是 `h5`，选项类型也要求提供它。 |
 
@@ -285,11 +347,11 @@ type VitePluginTaroOptions = {
 @source "./";
 ```
 
-插件会为 `h5` 构建注册 `@tailwindcss/vite`，并为 `wx` 构建注册 `weapp-tailwindcss`。对于 `wx`，Vite 输出的 CSS 会被收集到 `app.wxss`，并为每个页面生成配套的 `.wxss` 文件。
+插件会为 `wx` 构建注册 `weapp-tailwindcss`，并为 `h5` 构建注册 `@tailwindcss/vite`。对于 `wx`，Vite 输出的 CSS 会被收集到 `app.wxss`，并为每个页面生成配套的 `.wxss` 文件。
 
 ## 条件编译
 
-插件会在 Vite 解析源码之前移除非活动的 Taro 风格条件注释块。该能力适用于 `node_modules` 之外的 TypeScript、JavaScript、JSX/TSX、CSS、Sass、Less 和 Stylus 文件。
+插件会在 Vite 解析源码前移除未激活的 Taro 风格条件注释块。它适用于 `node_modules` 之外的 TypeScript、JavaScript、JSX/TSX、CSS、Sass、Less 和 Stylus 文件。
 
 ```ts
 // #ifdef wx
@@ -300,23 +362,19 @@ console.log('WeChat only')
 console.log('H5 only')
 // #endif
 
-// #if h5 && !wx
-console.log('H5 expression')
-// #elif wx
+// #if wx && !h5
 console.log('WeChat expression')
+// #elif h5
+console.log('H5 expression')
 // #else
 console.log('fallback')
 // #endif
 ```
 
-支持的指令包括 `#ifdef`、`#ifndef`、`#if`、`#elif`、`#else` 和 `#endif`。条件使用插件目标标记 `h5` 和 `wx`；`#if` 表达式支持 `!`、`&&` 和 `||`。
+支持的指令包括 `#ifdef`、`#ifndef`、`#if`、`#elif`、`#else` 和 `#endif`。条件使用插件目标标记 `wx` 和 `h5`；`#if` 表达式支持 `!`、`&&` 和 `||`。
 
 ## 按目标输出
 
-### H5
-
-对于 `target: 'h5'`，插件会向 `index.html` 注入生成模块，导入 Taro 的 H5 组件样式，根据 `pages` 构建路由记录，并使用 Taro 的 hash-history 路由挂载应用。路由使用配置中的页面路径，例如 `#/pages/index/index`。
-
 ### 微信小程序
 
 对于 `target: 'wx'`，插件会配置 Vite，输出微信兼容的 CommonJS chunk 和小程序配套文件。
@@ -340,38 +398,42 @@ dist/wx/
 
 请使用微信开发者工具打开 `dist/wx`；不要打开源码项目目录。
 
+### H5
+
+对于 `target: 'h5'`，插件会向 `index.html` 注入生成模块，导入 Taro 的 H5 组件样式，根据 `pages` 构建路由记录，并使用 Taro 的 hash-history 路由挂载应用。路由使用配置中的页面路径，例如 `#/pages/index/index`。
+
 ## 从 Taro 迁移
 
 你可以保留大多数 React 页面组件、业务逻辑、资源和样式，但构建入口会从 Taro CLI 配置迁移到 Vite 配置。
 
-迁移检查清单：
+迁移清单：
 
 1. 安装 `vite-plugin-taro`，并创建包含 `vitePluginTaro(...)` 的 `vite.config.ts`。
-2. 将应用配置和页面配置移入插件选项。插件不会读取 Taro CLI 文件，例如 `config/index.ts`、`app.config.ts` 或页面 `config.ts` 文件。
+2. 将应用配置和页面配置移到 `vite.config.ts` 中。插件不会读取 `config/index.ts`、`app.config.ts` 或页面 `config.ts` 等 Taro 文件。
 3. 在 `pages` 中注册每个页面。每个页面路径都必须匹配 `src/${path}.tsx`。
-4. 将 Taro 脚本替换为设置 `VITE_PLUGIN_TARO_TARGET=h5` 或 `VITE_PLUGIN_TARO_TARGET=wx` 的 Vite 脚本。
+4. 将 Taro 脚本替换为设置 `VITE_PLUGIN_TARO_TARGET=wx` 或 `VITE_PLUGIN_TARO_TARGET=h5` 的 Vite 脚本。
 5. 对于 H5，添加普通 Vite `index.html`，其中包含 `<div id="app"></div>`，且不要添加单独的 `src/main.tsx` 入口。
-6. 将应用中的 `@tarojs/*` 导入替换为插件虚拟模块。
+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 和微信构建都获得正确的目标特定别名。
+应用代码中禁止直接导入 `@tarojs/*`。请让插件负责 Taro 运行时解析，使微信和 H5 构建都获得正确的目标特定别名。
 
 ## 示例应用
 
-示例应用位于 [`packages/loan-genius`](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius)。它展示了页面约定、目标选择、H5 路由、Tailwind 样式和微信输出。
+示例应用位于 [`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
@@ -379,30 +441,29 @@ git clone https://github.com/sep2/vite-plugin-taro.git
 # 安装依赖
 pnpm install
 
-# 运行一次，用于生成打过补丁的 Taro 包
+# 首次运行，生成打过补丁的 Taro 包
 pnpm prepare:taro
 
-# 构建插件供示例应用使用
+# 构建插件，供示例应用使用
 pnpm build:plugin
 
+# 运行微信示例应用
+pnpm dev:sample:wx
+
+# 将示例应用构建为微信输出
+pnpm build:sample:wx
+
 # 以开发模式运行 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`，以测试小程序输出。
 
-
-## 开发此仓库
+## 开发本仓库
 
 ```sh
 pnpm install
@@ -415,35 +476,35 @@ pnpm typecheck
 
 | 脚本 | 描述 |
 | --- | --- |
-| `pnpm prepare:taro` | 从上游 npm tarball 和本地补丁文件重新生成打过补丁的 React 19 Taro 包。 |
+| `pnpm prepare:taro` | 从上游 npm tarball 和本地 patch 文件重新生成打过补丁的 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 dev:sample:h5` | 以 Vite 开发模式启动 H5 示例应用。请先构建插件。 |
+| `pnpm build:sample:wx` | 将微信小程序示例构建到 `packages/loan-genius/dist/wx`。 |
 | `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` | 按依赖顺序发布所有公开包。 |
+| `pnpm publish:dry` | 干运行包校验和发布流程。 |
+| `pnpm publish:all` | 按依赖顺序发布公开包。 |
 
 ## 限制
 
-- 目前只生成 `h5` 和 `wx` 目标。
-- 应用代码不得直接导入 `@tarojs/*` 包。
+- 目前只生成 `wx` 和 `h5` 目标。
+- 应用代码不能直接导入 `@tarojs/*` 包。
 
-
-## 故障排查
+## 排查问题
 
 | 问题 | 检查项 |
 | --- | --- |
-| `VITE_PLUGIN_TARO_TARGET must be "h5" or "wx"` | 在脚本或 `.env` 文件中设置目标环境变量。 |
+| `VITE_PLUGIN_TARO_TARGET must be "wx" or "h5"` | 在脚本或 `.env` 文件中设置目标环境变量。 |
+| `pnpm install` 提示忽略了依赖构建脚本 | 运行 `pnpm approve-builds`，按提示批准需要构建的依赖；如有需要再重新执行 `pnpm install`。 |
 | 页面无法解析 | 确认 `pages[].path` 有匹配的 `src/${path}.tsx` 文件。 |
+| 微信开发者工具无法打开应用 | 打开生成的 `dist/wx` 文件夹，并检查 `projectConfigJson.appid`。 |
 | 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` 路径。 |
 
 ## 发布流程
@@ -454,13 +515,12 @@ pnpm typecheck
 pnpm publish:dry
 ```
 
-按要求顺序发布所有公开包：
+按必要顺序发布所有公开包：
 
 ```sh
 pnpm publish:all
 ```
 
-
 ## 许可证
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-taro",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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.1",
-    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.1.1"
+    "@tarojs/react": "npm:vite-plugin-taro-react@0.1.2",
+    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.1.2"
   },
   "peerDependencies": {
     "react": "^19.0.0",