vite-plugin-taro 0.1.8 → 0.2.1

package/README.md

@@ -71,7 +71,7 @@ npm run build:h5
 # Preview the built H5 app
 npm run preview:h5
 
-# Typecheck with tsgo
+# Typecheck with tsc
 npm run typecheck
 ```
 
@@ -102,11 +102,11 @@ For existing apps or custom project layouts, follow the steps below to wire the
 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:
+Your app must also provide Vite 8, React 19, React DOM 19, TypeScript 7, and Node/React type packages. If your app does not already have them, install the missing packages:
 
 ```sh
 npm install react react-dom
-npm install -D vite @typescript/native-preview @types/node @types/react @types/react-dom
+npm install -D vite typescript@rc @types/node @types/react @types/react-dom cross-env
 ```
 
 You should NOT have direct dependencies on `@tarojs/*` packages anymore. Remove them if you have.
@@ -281,18 +281,16 @@ 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",
-        "preview:h5": "NODE_ENV=production VITE_PLUGIN_TARO_TARGET=h5 vite preview --outDir dist/h5",
-        "typecheck": "tsgo -b"
+        "dev:wx": "cross-env NODE_ENV=development VITE_PLUGIN_TARO_TARGET=wx vite build --watch",
+        "dev:h5": "cross-env NODE_ENV=development VITE_PLUGIN_TARO_TARGET=h5 vite",
+        "build:wx": "cross-env NODE_ENV=production VITE_PLUGIN_TARO_TARGET=wx vite build",
+        "build:h5": "cross-env NODE_ENV=production VITE_PLUGIN_TARO_TARGET=h5 vite build",
+        "preview:h5": "cross-env NODE_ENV=production VITE_PLUGIN_TARO_TARGET=h5 vite preview --outDir dist/h5",
+        "typecheck": "tsc -b"
     }
 }
 ```
 
-On Windows shells, use `cross-env`.
-
 ### 7. Run each target
 
 ```sh
@@ -301,7 +299,7 @@ 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
+npm run typecheck    # Typecheck with tsc
 ```
 
 Open the generated `dist/wx` directory in WeChat DevTools.
@@ -487,7 +485,7 @@ Common scripts:
 | --- | --- |
 | `pnpm prepare:taro` | Regenerate the patched React 19 Taro packages from upstream npm tarballs and local patch files. |
 | `pnpm build:plugin` | Build `packages/vite-plugin-taro` into `dist`. |
-| `pnpm typecheck` | Typecheck the plugin and sample app with `tsgo`. |
+| `pnpm typecheck` | Typecheck the plugin and sample app with `tsc`. |
 | `pnpm lint` | Run Biome checks. |
 | `pnpm format` | Apply Biome formatting. |
 | `pnpm dev:sample:wx` | Build the sample WeChat Mini Program in watch mode. Build the plugin first. |
@@ -495,8 +493,9 @@ Common scripts:
 | `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 changelog` | Regenerate `CHANGELOG.md` from git release tags. |
 | `pnpm publish:dry` | Dry-run package validation and publishing. |
-| `pnpm release <version\|bump>` | Validate, bump versions, create the release commit and tag, and push to trigger CI publishing. |
+| `pnpm release <version\|bump>` | Validate, bump versions, update the changelog, create the release commit and tag, and push to trigger CI publishing. |
 | `pnpm publish:all` | Publish the public packages in dependency order; mainly used by the tag-based Trusted Publishing workflow. |
 
 ## Limitations

package/README.zh.md

@@ -71,7 +71,7 @@ npm run build:h5
 # 预览构建后的 H5 应用
 npm run preview:h5
 
-# 使用 tsgo 进行类型检查
+# 使用 tsc 进行类型检查
 npm run typecheck
 ```
 
@@ -102,11 +102,11 @@ import { Text, View } from 'virtual:taro/components'
 npm install -D vite-plugin-taro
 ```
 
-你的应用还必须提供 Vite 8、React 19、React DOM 19、TypeScript 检查器，以及 Node/React 类型包。如果应用尚未安装它们，请安装缺失的包：
+你的应用还必须提供 Vite 8、React 19、React DOM 19、TypeScript 7，以及 Node/React 类型包。如果应用尚未安装它们，请安装缺失的包：
 
 ```sh
 npm install react react-dom
-npm install -D vite @typescript/native-preview @types/node @types/react @types/react-dom
+npm install -D vite typescript@rc @types/node @types/react @types/react-dom cross-env
 ```
 
 你不应再直接依赖任何 `@tarojs/*` 包。如果已经依赖，请将它们移除。
@@ -281,18 +281,16 @@ export default function IndexPage() {
 ```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",
-        "preview:h5": "NODE_ENV=production VITE_PLUGIN_TARO_TARGET=h5 vite preview --outDir dist/h5",
-        "typecheck": "tsgo -b"
+        "dev:wx": "cross-env NODE_ENV=development VITE_PLUGIN_TARO_TARGET=wx vite build --watch",
+        "dev:h5": "cross-env NODE_ENV=development VITE_PLUGIN_TARO_TARGET=h5 vite",
+        "build:wx": "cross-env NODE_ENV=production VITE_PLUGIN_TARO_TARGET=wx vite build",
+        "build:h5": "cross-env NODE_ENV=production VITE_PLUGIN_TARO_TARGET=h5 vite build",
+        "preview:h5": "cross-env NODE_ENV=production VITE_PLUGIN_TARO_TARGET=h5 vite preview --outDir dist/h5",
+        "typecheck": "tsc -b"
     }
 }
 ```
 
-在 Windows shell 中，请使用 `cross-env`。
-
 ### 7. 运行每个目标
 
 ```sh
@@ -301,7 +299,7 @@ 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 进行类型检查
+npm run typecheck    # 使用 tsc 进行类型检查
 ```
 
 在微信开发者工具中打开生成的 `dist/wx` 目录。
@@ -487,7 +485,7 @@ pnpm typecheck
 | --- | --- |
 | `pnpm prepare:taro` | 从上游 npm tarball 和本地 patch 文件重新生成打过补丁的 React 19 Taro 包。 |
 | `pnpm build:plugin` | 将 `packages/vite-plugin-taro` 构建到 `dist`。 |
-| `pnpm typecheck` | 使用 `tsgo` 对插件和示例应用进行类型检查。 |
+| `pnpm typecheck` | 使用 `tsc` 对插件和示例应用进行类型检查。 |
 | `pnpm lint` | 运行 Biome 检查。 |
 | `pnpm format` | 应用 Biome 格式化。 |
 | `pnpm dev:sample:wx` | 以 watch 模式构建微信小程序示例。请先构建插件。 |
@@ -495,8 +493,9 @@ pnpm typecheck
 | `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 changelog` | 从 git release tag 重新生成 `CHANGELOG.md`。 |
 | `pnpm publish:dry` | 干运行包校验和发布流程。 |
-| `pnpm release <version\|bump>` | 验证发布、更新版本、创建 release commit 和 tag，并推送触发 CI 发布。 |
+| `pnpm release <version\|bump>` | 验证发布、更新版本、更新 changelog、创建 release commit 和 tag，并推送触发 CI 发布。 |
 | `pnpm publish:all` | 按依赖顺序发布公开包；主要由基于 tag 的 Trusted Publishing 工作流调用。 |
 
 ## 限制

package/dist/vite/constants.js

@@ -1,10 +1,8 @@
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { toImportPath } from './utils.js';
 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, '/');
-}
+export const h5ShimImportPath = toImportPath(path.join(packageRoot, 'dist/shim/h5.js'));
+export const wxShimImportPath = toImportPath(path.join(packageRoot, 'dist/shim/wx.js'));

package/dist/vite/targets/h5.js

@@ -1,7 +1,7 @@
 import babel from '@rolldown/plugin-babel';
 import react from '@vitejs/plugin-react';
 import { h5ShimImportPath, isProd, nodeRequire } from '../constants.js';
-import { createPageComponentImport } from '../utils.js';
+import { createPageComponentImport, toImportPath } from '../utils.js';
 import { virtualTaroApiId } from '../virtual-modules.js';
 const virtualH5Id = 'virtual:vite-plugin-taro/h5';
 const patchStencilCssOrder = true;
@@ -149,8 +149,8 @@ export function createWebIndexHtmlTags(context) {
 export function createWebEntry(context) {
     const webAppConfigCode = JSON.stringify(createWebAppConfig(context.appConfig));
     const webRoutesConfigCode = createWebRoutesConfig(context.pages);
-    return `import ${JSON.stringify(nodeRequire.resolve('@tarojs/components/global.css'))}
-import ${JSON.stringify(nodeRequire.resolve('@tarojs/components/dist/taro-components/taro-components.css'))}
+    return `import ${JSON.stringify(toImportPath(nodeRequire.resolve('@tarojs/components/global.css')))}
+import ${JSON.stringify(toImportPath(nodeRequire.resolve('@tarojs/components/dist/taro-components/taro-components.css')))}
 import {
     createHashHistory,
     createReactApp,
@@ -160,7 +160,7 @@ import {
 } from ${JSON.stringify(h5ShimImportPath)}
 import React from 'react'
 import ReactDOM from 'react-dom/client'
-import AppComponent from '${context.appComponentImport}'
+import AppComponent from ${JSON.stringify(context.appComponentImport)}
 
 const config = window.__taroAppConfig = ${webAppConfigCode}
 config.routes = ${webRoutesConfigCode}

package/dist/vite/targets/wx.js

@@ -162,7 +162,7 @@ export function createWxAppEntry(context) {
     const wechatAppConfigCode = JSON.stringify(context.appConfig);
     return `import { createReactApp, ReactDOM } from ${JSON.stringify(wxShimImportPath)}
 import React from 'react'
-import AppComponent from '${context.appComponentImport}'
+import AppComponent from ${JSON.stringify(context.appComponentImport)}
 
 const appConfig = ${wechatAppConfigCode}
 App(createReactApp(AppComponent, React, ReactDOM, appConfig))
@@ -177,7 +177,7 @@ export function createWxPageEntry(pageOption) {
     const wechatPageConfigCode = JSON.stringify(pageOption.config);
     const pageComponentImport = createPageComponentImport(pageOption.path);
     return `import { createPageConfig } from ${JSON.stringify(wxShimImportPath)}
-import PageComponent from '${pageComponentImport}'
+import PageComponent from ${JSON.stringify(pageComponentImport)}
 
 const pageConfig = ${wechatPageConfigCode}
 const taroPageConfig = createPageConfig(PageComponent, '${pageOption.path}', { root: { cn: [] } }, pageConfig)

package/dist/vite/utils.js

@@ -10,10 +10,13 @@ export function createPageComponentImport(pagePath) {
     return toImportPath(`src/${pagePath}.tsx`);
 }
 /**
- * Converts a local file path into an absolute ESM import path for Vite.
+ * Converts a local file path into a Vite file-system import specifier.
+ *
+ * Rolldown does not reliably resolve raw Windows absolute paths from virtual
+ * module source, so generated imports use Vite's /@fs/ prefix instead.
  */
 export function toImportPath(filePath) {
-    return path.resolve(filePath);
+    return `/@fs/${normalizeModuleId(path.resolve(filePath))}`;
 }
 /**
  * Removes Rollup/Vite's internal virtual-module prefix before ID comparisons.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-taro",
-  "version": "0.1.8",
+  "version": "0.2.1",
   "author": "sep2",
   "description": "Vite 8 plugin for building one React/Taro codebase for WeChat Mini Program and H5 targets.",
   "type": "module",
@@ -32,7 +32,6 @@
     "client.d.ts",
     "LICENSE",
     "README.md",
-    "README.en.md",
     "README.zh.md"
   ],
   "keywords": [
@@ -65,8 +64,8 @@
     "babel-plugin-transform-taroapi": "^4.2.0",
     "tailwindcss": "^4.3.1",
     "weapp-tailwindcss": "^5.0.13",
-    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.1.8",
-    "@tarojs/react": "npm:vite-plugin-taro-react@0.1.8"
+    "@tarojs/react": "npm:vite-plugin-taro-react@0.2.1",
+    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.2.1"
   },
   "peerDependencies": {
     "react": "^19.0.0",
@@ -76,11 +75,11 @@
   "devDependencies": {
     "@types/babel__core": "^7.20.5",
     "@types/node": "^26.0.0",
-    "@typescript/native-preview": "latest",
+    "typescript": "^7.0.1-rc",
     "vite": "^8.0.16"
   },
   "scripts": {
-    "build": "node ../../scripts/sync-plugin-readme.ts && rm -rf dist && tsgo --project tsconfig.json",
-    "typecheck": "tsgo --project tsconfig.json --noEmit"
+    "build": "node ../../scripts/sync-plugin-readme.ts && node ../../scripts/clean-directory.ts dist && tsc --project tsconfig.json",
+    "typecheck": "tsc --project tsconfig.json --noEmit"
   }
 }

package/src/vite/constants.ts

@@ -1,5 +1,6 @@
 import { createRequire } from 'node:module'
 import path from 'node:path'
+import { toImportPath } from './utils.ts'
 
 export const isProd = process.env.NODE_ENV === 'production'
 
@@ -7,9 +8,5 @@ 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: string): string {
-    return filePath.replace(/\\/g, '/')
-}
+export const h5ShimImportPath = toImportPath(path.join(packageRoot, 'dist/shim/h5.js'))
+export const wxShimImportPath = toImportPath(path.join(packageRoot, 'dist/shim/wx.js'))

package/src/vite/targets/h5.ts

@@ -4,7 +4,7 @@ import react from '@vitejs/plugin-react'
 import type { HtmlTagDescriptor, PluginOption, UserConfig } from 'vite'
 import { h5ShimImportPath, isProd, nodeRequire } from '../constants.ts'
 import type { JsonObject, VitePluginTaroBuildContext, VitePluginTaroPageOption } from '../types.ts'
-import { createPageComponentImport } from '../utils.ts'
+import { createPageComponentImport, toImportPath } from '../utils.ts'
 import { virtualTaroApiId } from '../virtual-modules.ts'
 
 const virtualH5Id = 'virtual:vite-plugin-taro/h5'
@@ -173,8 +173,8 @@ export function createWebEntry(context: VitePluginTaroBuildContext): string {
     const webAppConfigCode = JSON.stringify(createWebAppConfig(context.appConfig))
     const webRoutesConfigCode = createWebRoutesConfig(context.pages)
 
-    return `import ${JSON.stringify(nodeRequire.resolve('@tarojs/components/global.css'))}
-import ${JSON.stringify(nodeRequire.resolve('@tarojs/components/dist/taro-components/taro-components.css'))}
+    return `import ${JSON.stringify(toImportPath(nodeRequire.resolve('@tarojs/components/global.css')))}
+import ${JSON.stringify(toImportPath(nodeRequire.resolve('@tarojs/components/dist/taro-components/taro-components.css')))}
 import {
     createHashHistory,
     createReactApp,
@@ -184,7 +184,7 @@ import {
 } from ${JSON.stringify(h5ShimImportPath)}
 import React from 'react'
 import ReactDOM from 'react-dom/client'
-import AppComponent from '${context.appComponentImport}'
+import AppComponent from ${JSON.stringify(context.appComponentImport)}
 
 const config = window.__taroAppConfig = ${webAppConfigCode}
 config.routes = ${webRoutesConfigCode}

package/src/vite/targets/wx.ts

@@ -212,7 +212,7 @@ export function createWxAppEntry(context: VitePluginTaroBuildContext): string {
 
     return `import { createReactApp, ReactDOM } from ${JSON.stringify(wxShimImportPath)}
 import React from 'react'
-import AppComponent from '${context.appComponentImport}'
+import AppComponent from ${JSON.stringify(context.appComponentImport)}
 
 const appConfig = ${wechatAppConfigCode}
 App(createReactApp(AppComponent, React, ReactDOM, appConfig))
@@ -228,7 +228,7 @@ export function createWxPageEntry(pageOption: VitePluginTaroPageOption): string
     const wechatPageConfigCode = JSON.stringify(pageOption.config)
     const pageComponentImport = createPageComponentImport(pageOption.path)
     return `import { createPageConfig } from ${JSON.stringify(wxShimImportPath)}
-import PageComponent from '${pageComponentImport}'
+import PageComponent from ${JSON.stringify(pageComponentImport)}
 
 const pageConfig = ${wechatPageConfigCode}
 const taroPageConfig = createPageConfig(PageComponent, '${pageOption.path}', { root: { cn: [] } }, pageConfig)

package/src/vite/utils.ts

@@ -12,10 +12,13 @@ export function createPageComponentImport(pagePath: string): string {
 }
 
 /**
- * Converts a local file path into an absolute ESM import path for Vite.
+ * Converts a local file path into a Vite file-system import specifier.
+ *
+ * Rolldown does not reliably resolve raw Windows absolute paths from virtual
+ * module source, so generated imports use Vite's /@fs/ prefix instead.
  */
 export function toImportPath(filePath: string): string {
-    return path.resolve(filePath)
+    return `/@fs/${normalizeModuleId(path.resolve(filePath))}`
 }
 
 /**

package/README.en.md

@@ -1,543 +0,0 @@
-# vite-plugin-taro
-
-[![npm version](https://img.shields.io/npm/v/vite-plugin-taro.svg)](https://www.npmjs.com/package/vite-plugin-taro)
-![Vite compatibility](https://registry.vite.dev/api/badges?package=vite-plugin-taro&tool=vite)
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-
-[简体中文](README.zh.md) | English
-
-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. You only need this plugin to build a complete WeChat Mini Program.
-
-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.md) how to run it locally.
-
-- **Native Vite builds** Use standard Vite 8 config instead of legacy webpack configuration, with support for all Vite plugins.
-- **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 WeChat Mini Program and H5 styles.
-- **Conditional compilation** Use Taro-style `#ifdef` / `#ifndef` / `#if` blocks to split code and styles by WeChat / web target.
-- **Workspace friendly** Supports standalone apps and monorepos, with npm, pnpm, Yarn, Bun, and other package managers.
-- **Type-friendly** The project supports TypeScript all the way.
-- **WeChat Skyline** Support WeChat Mini Program output with Skyline rendering mode.
-
-## Quick start
-
-Use `create-vite-taro` for new apps. It scaffolds a Vite 8 + React 19 + Tailwind CSS v4 + Taro 4 project.
-
-### 1. Create and install
-
-```sh
-# Create a new app from the default template
-npm create vite-taro@latest my-app
-
-# Enter the project and install dependencies
-cd my-app
-npm install
-```
-
-### 2. Configure WeChat Mini Program App ID
-
-The template creates `.env.local`. Set `VITE_PLUGIN_TARO_WECHAT_APP_ID` to your WeChat Mini Program App ID.
-
-### 3. Run in development
-
-```sh
-# WeChat Mini Program: rebuild dist/wx in watch mode
-npm run dev:wx
-
-# Then open dist/wx in WeChat DevTools
-
-# H5: start the Vite dev server
-npm run dev:h5
-
-# Then open the standard Vite dev URL in your browser
-# http://localhost:5173
-```
-
-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.
-
-### 4. Build, preview, and typecheck
-
-```sh
-# Production WeChat Mini Program output
-npm run build:wx
-
-# Production H5 output
-npm run build:h5
-
-# Preview the built H5 app
-npm run preview:h5
-
-# Typecheck with tsgo
-npm run typecheck
-```
-
-### 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
-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
-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.
-
-The steps below create this source shape:
-
-```text
-my-app/
-├── index.html
-├── package.json
-├── tsconfig.json
-├── vite.config.ts
-└── src/
-    ├── app.css
-    ├── app.ts
-    └── pages/
-        └── index/
-            └── index.tsx
-```
-
-You can also see a sample layout at [packages/loan-genius](https://github.com/sep2/vite-plugin-taro/tree/main/packages/loan-genius).
-
-### 1. Add TypeScript declarations
-
-Add the plugin client types to `tsconfig.json` so TypeScript knows about the virtual modules:
-
-```json
-{
-    "compilerOptions": {
-        "jsx": "react-jsx",
-        "moduleResolution": "bundler",
-        "types": ["vite/client", "vite-plugin-taro/client"]
-    },
-    "include": ["src"]
-}
-```
-
-### 2. Configure Vite
-
-Create `vite.config.ts` and choose the plugin target from an environment variable:
-
-```ts
-import { defineConfig, loadEnv } from 'vite'
-import vitePluginTaro, { type VitePluginTaroTarget } from 'vite-plugin-taro'
-
-const targetEnvName = 'VITE_PLUGIN_TARO_TARGET'
-
-function getTarget(env: Record<string, string>): VitePluginTaroTarget {
-    const target = env[targetEnvName]
-    if (target === 'wx' || target === 'h5') return target
-    throw new Error(`${targetEnvName} must be "wx" or "h5".`)
-}
-
-export default defineConfig(({ mode }) => {
-    const env = loadEnv(mode, process.cwd(), 'VITE_PLUGIN_TARO_')
-    const target = getTarget(env)
-
-    return {
-        build: {
-            outDir: `dist/${target}`
-        },
-        plugins: [
-            vitePluginTaro({
-                target,
-                app: 'src/app.ts',
-                pages: [
-                    {
-                        path: 'pages/index/index',
-                        config: {
-                            navigationBarTitleText: 'Home'
-                        }
-                    }
-                ],
-                appJson: {
-                    window: {
-                        navigationBarTitleText: 'Demo',
-                        navigationBarBackgroundColor: '#ffffff'
-                    }
-                },
-                projectConfigJson: {
-                    appid: env.VITE_PLUGIN_TARO_WECHAT_APP_ID || 'touristappid',
-                    projectname: 'demo',
-                    compileType: 'miniprogram'
-                },
-                sitemapJson: {
-                    rules: [{ action: 'allow', page: '*' }]
-                }
-            })
-        ]
-    }
-})
-```
-
-Important conventions:
-
-- `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.
-- The plugin does not read Taro CLI config files such as `config/index.ts`, `app.config.ts`, or page `config.ts` files. Pass app and page config through the plugin options.
-
-### 3. Create the app component
-
-`src/app.ts` is the shared application wrapper. It receives the current page as `children`.
-
-```tsx
-import Taro from 'virtual:taro/api'
-import type { PropsWithChildren } from 'react'
-import './app.css'
-
-function App({ children }: PropsWithChildren) {
-    Taro.useLaunch(() => {
-        console.log('App launched')
-    })
-
-    return children
-}
-
-export default App
-```
-
-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 Taro from 'virtual:taro/api'
-import { Button, Text, View } from 'virtual:taro/components'
-
-export default function IndexPage() {
-    const windowInfo = Taro.getWindowInfo()
-
-    return (
-        <View className="p-4">
-            <Text>Viewport width: {windowInfo.windowWidth}</Text>
-            <Button
-                onClick={() => {
-                    Taro.showToast({ title: 'Hello from Taro' })
-                }}
-            >
-                Show toast
-            </Button>
-        </View>
-    )
-}
-```
-
-### 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.
-
-```html
-<!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>
-```
-
-### 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",
-        "preview:h5": "NODE_ENV=production VITE_PLUGIN_TARO_TARGET=h5 vite preview --outDir dist/h5",
-        "typecheck": "tsgo -b"
-    }
-}
-```
-
-On Windows shells, use `cross-env`.
-
-### 7. Run each target
-
-```sh
-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.
-
-| Target | Meaning | Output dir |
-| --- | --- | --- |
-| `wx` | WeChat Mini Program in both dev/prod mode. | `dist/wx` |
-| `h5` | H5 production output. | `dist/h5` |
-
-## Options
-
-```ts
-type VitePluginTaroTarget = 'wx' | 'h5'
-
-type VitePluginTaroPageOption = {
-    path: string
-    config: Record<string, unknown>
-}
-
-type VitePluginTaroOptions = {
-    target: VitePluginTaroTarget
-    app: string
-    pages: VitePluginTaroPageOption[]
-    appJson: Record<string, unknown>
-    projectConfigJson: Record<string, unknown>
-    sitemapJson: Record<string, unknown>
-}
-```
-
-| Option | Description |
-| --- | --- |
-| `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`. |
-| `pages[].config` | Page config merged into the generated WeChat page JSON and H5 route config. |
-| `appJson` | Base app config. The plugin overwrites the `pages` field from `options.pages`. |
-| `projectConfigJson` | WeChat `project.config.json` content emitted for `wx` builds. It is required by the option type even when the current target is `h5`. |
-| `sitemapJson` | WeChat `sitemap.json` content emitted for `wx` builds. It is required by the option type even when the current target is `h5`. |
-
-## Styling
-
-You can use plain CSS, CSS modules, or Tailwind CSS v4.
-
-For Tailwind CSS v4, import Tailwind from a global CSS file such as `src/app.css`:
-
-```css
-@import "tailwindcss/theme.css";
-@import "tailwindcss/preflight.css";
-@import "tailwindcss/utilities.css";
-
-@source "./";
-```
-
-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
-
-The plugin strips inactive Taro-style conditional comment blocks before Vite parses source. This works in TypeScript, JavaScript, JSX/TSX, CSS, Sass, Less, and Stylus files outside `node_modules`.
-
-```ts
-// #ifdef wx
-console.log('WeChat only')
-// #endif
-
-// #ifdef h5
-console.log('H5 only')
-// #endif
-
-// #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 `wx` and `h5`; `#if` expressions support `!`, `&&`, and `||`.
-
-## Output by target
-
-### WeChat Mini Program
-
-For `target: 'wx'`, the plugin configures Vite to emit WeChat-compatible CommonJS chunks and Mini Program companion files.
-
-Typical output:
-
-```text
-dist/wx/
-├── app.js
-├── app.json
-├── app.wxss
-├── base.wxml
-├── comp.js
-├── comp.json
-├── comp.wxml
-├── project.config.json
-├── sitemap.json
-├── utils.wxs
-└── pages/**
-```
-
-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.
-
-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=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.
-
-Before:
-
-```tsx
-import Taro from '@tarojs/taro'
-import { Text, View } from '@tarojs/components'
-```
-
-After:
-
-```tsx
-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 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, WeChat output, H5 routing, and Tailwind styling.
-
-```sh
-git clone https://github.com/sep2/vite-plugin-taro.git
-
-# Install dependencies
-pnpm install
-
-# Run once, it generates the patched Taro packages
-pnpm prepare:taro
-
-# Build the plugin for sample app to use
-pnpm build:plugin
-
-# 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
-pnpm install
-pnpm prepare:taro
-pnpm build:plugin
-pnpm typecheck
-```
-
-Common scripts:
-
-| Script | Description |
-| --- | --- |
-| `pnpm prepare:taro` | Regenerate the patched React 19 Taro packages from upstream npm tarballs and local patch files. |
-| `pnpm build:plugin` | Build `packages/vite-plugin-taro` into `dist`. |
-| `pnpm typecheck` | Typecheck the plugin and sample app with `tsgo`. |
-| `pnpm lint` | Run Biome checks. |
-| `pnpm format` | Apply Biome formatting. |
-| `pnpm dev:sample:wx` | Build the sample WeChat Mini Program in watch mode. Build the plugin first. |
-| `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 publish:dry` | Dry-run package validation and publishing. |
-| `pnpm release <version\|bump>` | Validate, bump versions, create the release commit and tag, and push to trigger CI publishing. |
-| `pnpm publish:all` | Publish the public packages in dependency order; mainly used by the tag-based Trusted Publishing workflow. |
-
-## Limitations
-
-- 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 "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` 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. |
-| 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. |
-| Tailwind classes do not appear | Ensure your global CSS imports Tailwind and includes an `@source` path that covers your source files. |
-
-## Release workflow
-
-This repository publishes automatically with npm Trusted Publishing and GitHub Actions. Normal pushes to `main` do not publish; only tags matching `v*.*.*` trigger `.github/workflows/publish.yml`.
-
-Create a release:
-
-```sh
-pnpm release patch
-```
-
-`pnpm release` requires a clean `main` working tree, runs `pnpm version:bump`, validates with `pnpm publish:dry -- --no-git-check`, creates the `chore: release vX.Y.Z` commit and `vX.Y.Z` tag, then pushes the branch and tag to trigger CI. You can also release an exact version or prerelease:
-
-```sh
-pnpm release 0.2.0
-pnpm release prerelease --preid beta
-pnpm release patch --dry-run
-pnpm release patch --no-push
-```
-
-CI runs `pnpm publish:all -- --no-git-check`, packs packages in dependency order, and publishes public packages through npm OIDC. Do not configure `NPM_TOKEN` for the publish workflow; each npm package's Trusted Publisher should point to `publish.yml`.
-
-## License
-
-MIT