vite-plugin-taro 0.2.2 → 0.3.0

package/README.md

@@ -6,20 +6,20 @@
 
 [简体中文](README.zh.md) | English
 
-Build WeChat Mini Apps with the latest standards-based frontend stack: Vite 8, React 19, and Tailwind CSS v4.
+Build WeChat Mini Program and Web apps with the latest standards-based frontend stack: Vite 8, React 19, Taro 4, 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.
+`vite-plugin-taro` is for teams building Taro React apps with Vite: keep Taro's cross-platform components and APIs, leave Taro webpack behind, and fix/avoid common official Taro Vite pitfalls. One plugin builds WeChat Mini Program and Web.
 
-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.
+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) for 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.
+- **Vite 8 + React 19** Build one codebase for WeChat Mini Program and Web with the Vite ecosystem.
+- **Hot reload** Re-engineered on Vite with seamless WeChat Mini Program support, so page edits no longer lose state.
+- **Tailwind CSS v4 ready** Write utility classes directly; WeChat and Web styles adapt automatically.
+- **Built on Taro, beyond Taro** Use Taro components and APIs while leaving the old webpack pipeline behind.
+- **Skyline ready** Support WeChat Skyline rendering mode perfectly.
+- **Conditional compilation** Split code and styles with Taro-style `#ifdef` / `#ifndef` blocks.
+- **Workspace friendly** Supports standalone apps and monorepos, compatible with `npm`, `pnpm`, `Yarn`, and `Bun`.
+- **TypeScript friendly** Type support from config to app code.
 
 ## Quick start
 
@@ -31,6 +31,9 @@ Use `create-vite-taro` for new apps. It scaffolds a Vite 8 + React 19 + Tailwind
 # Create a new app from the default template
 npm create vite-taro@latest my-app
 
+# Or create with pnpm
+pnpm --config.minimum-release-age=0 create vite-taro@latest my-app
+
 # Enter the project and install dependencies
 cd my-app
 npm install
@@ -43,7 +46,7 @@ The template creates `.env.local`. Set `VITE_PLUGIN_TARO_WECHAT_APP_ID` to your
 ### 3. Run in development
 
 ```sh
-# WeChat Mini Program: rebuild dist/wx in watch mode
+# WeChat Mini Program: start Vite with hot reload
 npm run dev:wx
 
 # Then open dist/wx in WeChat DevTools
@@ -57,7 +60,7 @@ npm run dev:h5
 
 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.
+WX development provides full Vite-powered hot reload through Rolldown's incremental module graph and React Refresh. JavaScript edits preserve the active native page and React/input state; CSS, assets, public files, and configuration changes are rebuilt automatically.
 
 ### 4. Build, preview, and typecheck
 
@@ -93,7 +96,6 @@ Usage is the same as Taro itself; see the [Taro website](https://docs.taro.zone)
 
 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:
@@ -109,7 +111,7 @@ npm install react 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.
+Remove all `@tarojs/*` packages from `dependencies` and `devDependencies`.
 
 The steps below create this source shape:
 
@@ -172,19 +174,9 @@ export default defineConfig(({ mode }) => {
             vitePluginTaro({
                 target,
                 app: 'src/app.ts',
-                pages: [
-                    {
-                        path: 'pages/index/index',
-                        config: {
-                            navigationBarTitleText: 'Home'
-                        }
-                    }
-                ],
+                pages: [{ path: 'pages/index/index', config: { navigationBarTitleText: 'Home' } }],
                 appJson: {
-                    window: {
-                        navigationBarTitleText: 'Demo',
-                        navigationBarBackgroundColor: '#ffffff'
-                    }
+                    window: { navigationBarTitleText: 'Demo' }
                 },
                 projectConfigJson: {
                     appid: env.VITE_PLUGIN_TARO_WECHAT_APP_ID || 'touristappid',
@@ -206,6 +198,7 @@ Important conventions:
 - `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.
+- If your app uses Skyline, add the related `appJson` and `projectConfigJson` settings.
 - 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
@@ -213,75 +206,62 @@ Important conventions:
 `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')
-    })
-
+export default function App({ children }: PropsWithChildren) {
     return children
 }
+```
+
+Import global styles from the app component. The next step creates `src/app.css`.
+
+### 4. Create global styles
+
+`src/app.css` can use plain CSS, component CSS modules, and Tailwind CSS v4. The plugin injects Taro H5 component styles automatically; the default global stylesheet enables Tailwind CSS v4 for both targets:
+
+```css
+@import "tailwindcss/theme.css";
+@import "tailwindcss/preflight.css";
+@import "tailwindcss/utilities.css";
 
-export default App
+@source "./";
 ```
 
-Import global styles from the app component. They are collected into `app.wxss` for WeChat builds and included in H5 output.
+Keep `@source "./";` so Tailwind scans your source tree.
 
-### 4. Create a page component
+### 5. 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'
+import { 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>
+            <Text>Hello Taro</Text>
         </View>
     )
 }
 ```
 
-### 5. Add the H5 HTML shell
+### 6. 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>
+<div id="app"></div>
 ```
 
-### 6. Add scripts
+### 7. Add scripts
 
 Use the same scripts generated by `create-vite-taro`:
 
 ```json
 {
     "scripts": {
-        "dev:wx": "cross-env NODE_ENV=development VITE_PLUGIN_TARO_TARGET=wx vite build --watch",
+        "dev:wx": "cross-env NODE_ENV=development VITE_PLUGIN_TARO_TARGET=wx vite",
         "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",
@@ -291,10 +271,10 @@ Use the same scripts generated by `create-vite-taro`:
 }
 ```
 
-### 7. Run each target
+### 8. Run each target
 
 ```sh
-npm run dev:wx       # Rebuild dist/wx in watch mode
+npm run dev:wx       # Start WX development with hot reload
 npm run dev:h5       # Start the H5 dev server
 npm run build:wx     # Build dist/wx
 npm run build:h5     # Build dist/h5
@@ -304,6 +284,8 @@ npm run typecheck    # Typecheck with tsc
 
 Open the generated `dist/wx` directory in WeChat DevTools.
 
+WX development completes an eager build of the App and every configured page before Vite reports ready. JavaScript and TypeScript component edits use React Refresh and preserve compatible React state, the current Taro page, and native input state. Module-local state resets on each code update. Changes to CSS, assets, or app configuration intentionally perform a complete rebuild and DevTools reload. The generated development project enables WeChat's `compileHotReLoad` setting automatically.
+
 | Target | Meaning | Output dir |
 | --- | --- | --- |
 | `wx` | WeChat Mini Program in both dev/prod mode. | `dist/wx` |
@@ -333,29 +315,13 @@ type VitePluginTaroOptions = {
 | --- | --- |
 | `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` | Ordered page list. The order becomes `app.json.pages` and the Web 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`. |
+| `pages[].config` | Page config merged into the generated WeChat page JSON and Web route config. |
+| `appJson` | Base app config shared by both targets. 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`.
@@ -369,16 +335,14 @@ console.log('WeChat only')
 console.log('H5 only')
 // #endif
 
-// #if wx && !h5
-console.log('WeChat expression')
-// #elif h5
-console.log('H5 expression')
+// #ifndef h5
+console.log('Not H5')
 // #else
-console.log('fallback')
+console.log('H5 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 `||`.
+Supported directives are `#ifdef`, `#ifndef`, `#else`, and `#endif`. Conditions use the plugin target tokens `wx` and `h5`.
 
 ## Output by target
 
@@ -405,9 +369,9 @@ dist/wx/
 
 Open `dist/wx` with WeChat DevTools; do not open the source project directory.
 
-### H5
+### H5 / Web
 
-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`.
+For `target: 'h5'`, the plugin injects a generated module into `index.html`, imports Taro H5 component styles before the app, 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
 
@@ -416,11 +380,13 @@ You can keep most React page components, business logic, assets, and styles, but
 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.
+2. Move app config and page config into `vite.config.ts`. The plugin does not read Taro files such as `config/index.ts`, `app.config.ts`, or page `config.ts`.
 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.
+6. Move global styles to `src/app.css`, keep `import './app.css'` in the app entry, and add the Taro/Tailwind imports shown below.
+7. Remove all `@tarojs/*` packages from `dependencies` and `devDependencies`.
+8. Replace application imports from `@tarojs/*` with the plugin virtual modules.
 
 Before:
 
@@ -436,7 +402,17 @@ 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.
+Style migration:
+
+```css
+@import "tailwindcss/theme.css";
+@import "tailwindcss/preflight.css";
+@import "tailwindcss/utilities.css";
+
+@source "./";
+```
+
+Remove all `@tarojs/*` packages and do not import them directly in application code. Let the plugin own Taro runtime resolution.
 
 ## Sample app
 
@@ -455,17 +431,17 @@ pnpm prepare:taro
 pnpm build:plugin
 
 # Run the sample app in WeChat
-pnpm dev:sample:wx
+pnpm dev:loan-genius:wx
 
 # Build the sample app to WeChat output
-pnpm build:sample:wx
+pnpm build:loan-genius:wx
 
 # Run the sample app in H5 dev mode
-pnpm dev:sample:h5
+pnpm dev:loan-genius:h5
 
 # Build the sample app to H5 output and preview it
-pnpm build:sample:h5
-pnpm preview:sample:h5
+pnpm build:loan-genius:h5
+pnpm preview:loan-genius:h5
 ```
 
 Open `packages/loan-genius/dist/wx` with WeChat DevTools to test the Mini Program output.
@@ -488,11 +464,11 @@ Common scripts:
 | `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. |
-| `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 dev:loan-genius:wx` | Start the WeChat Mini Program sample with hot reload. Build the plugin first. |
+| `pnpm dev:loan-genius:h5` | Start the H5 sample app in Vite dev mode. Build the plugin first. |
+| `pnpm build:loan-genius:wx` | Build the WeChat Mini Program sample to `packages/loan-genius/dist/wx`. |
+| `pnpm build:loan-genius:h5` | Build the H5 sample app to `packages/loan-genius/dist/h5`. |
+| `pnpm preview:loan-genius: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, update the changelog, create the release commit and tag, and push to trigger CI publishing. |
@@ -500,6 +476,7 @@ Common scripts:
 
 ## Limitations
 
+- Only React apps are supported today.
 - Only `wx` and `h5` targets are generated today.
 - Application code must not import `@tarojs/*` packages directly.
 
@@ -513,8 +490,8 @@ Common scripts:
 | 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. |
+| Components render without expected styles on H5 | Ensure the app entry imports `./app.css` and the generated H5 entry is injected into `index.html`. |
+| Tailwind classes do not appear | Ensure `src/app.css` imports Tailwind's CSS files, keeps `@source "./";`, and class names are statically discoverable. Restart the dev server after moving files. |
 
 ## Release workflow