vite-plugin-taro 0.0.3 → 0.0.4

package/README.md

@@ -1,114 +1,159 @@
 # vite-plugin-taro
 
-Vite 8 + React 19 plugin for building one React/Taro codebase for both WeChat Mini Program (`wx`) and Web (`h5`) targets.
+[![npm version](https://img.shields.io/npm/v/vite-plugin-taro.svg)](https://www.npmjs.com/package/vite-plugin-taro)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-- npm: <https://www.npmjs.com/package/vite-plugin-taro>
-- Sample H5 demo: <https://sep2.github.io/vite-plugin-taro/>
-- Repository: <https://github.com/sep2/vite-plugin-taro>
+Vite 8 plugin for building one React 19 + Taro 4 app as either Web (`h5`) or WeChat Mini Program (`wx`).
 
-## Features
+## Highlights
 
-- `wx` target: emits WeChat Mini Program JS/JSON/WXML/WXSS assets.
-- `h5` target: emits a Web app using the Taro H5 runtime and router.
-- React 19 support via patched Taro runtime packages published as npm aliases.
-- No app-side `patchedDependencies` required.
-- Taro-style conditional compilation comments for TS/JS/JSX/TSX and style files.
-- Target-specific Vite/Rolldown and WeChat output setup.
+- Builds the same React/Taro pages for `h5` and `wx` targets.
+- Uses React 19-compatible Taro React packages published by this monorepo.
+- Generates Taro-style app/page entries instead of requiring generated files in your app source.
+- Emits WeChat Mini Program assets: `app.json`, page JSON, WXML, WXS, WXSS, and CommonJS chunks.
+- Boots H5 with Taro's official router/runtime and component CSS.
+- Handles Tailwind CSS v4 for H5 and transforms Tailwind output for WeChat Mini Programs.
+- Strips inactive Taro-style conditional compilation blocks before Vite parses code.
+- Provides app-facing facades for Taro APIs and components.
+
+## Compatibility
+
+| Dependency | Supported version |
+| --- | --- |
+| Node.js | `^20.19.0` or `>=22.12.0` |
+| Vite | `^8.0.0` |
+| React / React DOM | `^19.0.0` |
+| Taro runtime packages | `4.2.0` |
+| Tailwind CSS | `4.x` |
 
 ## Install
 
 ```sh
-pnpm add -D vite-plugin-taro vite
+pnpm add -D vite vite-plugin-taro
 pnpm add react react-dom
 ```
 
-## Vite usage
+## Package exports
+
+| Import | Use |
+| --- | --- |
+| `vite-plugin-taro/vite` | Recommended Vite plugin entry. Exports the default plugin plus option/target types. |
+| `vite-plugin-taro` | Same plugin entry as `vite-plugin-taro/vite`. |
+| `vite-plugin-taro/components` | Re-export of Taro React components. Use this in application code. |
+| `vite-plugin-taro/taro` | Taro API facade. Use this instead of importing `@tarojs/taro` directly. |
+| `vite-plugin-taro/shim/h5` | Internal H5 runtime shim used by generated entries. |
+| `vite-plugin-taro/shim/wx` | Internal WeChat runtime shim used by generated entries. |
+
+Application code should normally use only `vite-plugin-taro/components` and `vite-plugin-taro/taro`.
+
+## Minimal setup
+
+### Vite config
 
 ```ts
-import taro from 'vite-plugin-taro/vite'
 import { defineConfig, loadEnv } from 'vite'
+import vitePluginTaro, { type VitePluginTaroTarget } from 'vite-plugin-taro/vite'
+
+function getTarget(value: string | undefined): VitePluginTaroTarget {
+    if (value === 'h5' || value === 'wx') return value
+    throw new Error('VITE_PLUGIN_TARO_TARGET must be "h5" or "wx".')
+}
 
 export default defineConfig(({ mode }) => {
     const env = loadEnv(mode, process.cwd(), 'VITE_PLUGIN_TARO_')
-    const target = env.VITE_PLUGIN_TARO_TARGET as 'wx' | 'h5'
+    const target = getTarget(env.VITE_PLUGIN_TARO_TARGET)
 
     return {
         base: target === 'h5' ? './' : undefined,
+        build: {
+            outDir: `dist/${target}`
+        },
         plugins: [
-            taro({
+            vitePluginTaro({
                 target,
                 app: 'src/app.ts',
-                pages: [{ path: 'pages/index/index', config: {} }],
+                pages: [
+                    {
+                        path: 'pages/index/index',
+                        config: {
+                            navigationBarTitleText: 'Home'
+                        }
+                    }
+                ],
                 appJson: {},
                 projectConfigJson: {
                     appid: env.VITE_PLUGIN_TARO_WECHAT_APP_ID || 'touristappid'
                 },
-                sitemapJson: { rules: [{ action: 'allow', page: '*' }] }
+                sitemapJson: {
+                    rules: [{ action: 'allow', page: '*' }]
+                }
             })
         ]
     }
 })
 ```
 
-Example scripts:
+### App component
 
-```json
-{
-    "scripts": {
-        "build:h5": "NODE_ENV=production VITE_PLUGIN_TARO_TARGET=h5 vite build",
-        "build:wx": "NODE_ENV=production VITE_PLUGIN_TARO_TARGET=wx vite build",
-        "dev:h5": "NODE_ENV=development VITE_PLUGIN_TARO_TARGET=h5 vite",
-        "dev:wx": "NODE_ENV=development VITE_PLUGIN_TARO_TARGET=wx vite build --watch"
-    }
-}
-```
+`app` points to a module that default-exports the root React app component.
 
-Application code should usually import only from the plugin virtual modules. `virtual:taro` is default-export only; call APIs as `Taro.xxx`.
+```tsx
+// src/app.ts
+import type { PropsWithChildren } from 'react'
+import Taro from 'vite-plugin-taro/taro'
+import './app.css'
 
-```ts
-import Taro from 'virtual:taro'
-import { Text, View } from 'virtual:taro/components'
+export default function App({ children }: PropsWithChildren) {
+    Taro.useLaunch(() => {
+        console.log('App launch')
+    })
 
-Taro.useLaunch(() => {})
-Taro.getWindowInfo()
+    return children
+}
 ```
 
-For Taro namespace types:
+### Page component
 
-```ts
-import type Taro from 'virtual:taro'
+Each `pages[].path` maps to `src/${path}.tsx`.
 
-type Color = Taro.Color
-```
+```tsx
+// src/pages/index/index.tsx
+import { Text, View } from 'vite-plugin-taro/components'
+import Taro from 'vite-plugin-taro/taro'
 
-Add the virtual module declarations to the app `tsconfig.json`:
+export default function IndexPage() {
+    const windowInfo = Taro.getWindowInfo()
 
-```json
-{
-    "compilerOptions": {
-        "types": ["vite/client", "vite-plugin-taro/client"]
-    }
+    return (
+        <View>
+            <Text>Viewport width: {windowInfo.windowWidth}</Text>
+        </View>
+    )
 }
 ```
 
-## Styling
+### HTML shell for H5
 
-`vite-plugin-taro` does not bundle a Tailwind or `weapp-tailwindcss` pipeline. Add styling plugins directly in the app's Vite config when needed. See [`loan-genius`](../loan-genius) for an example using Tailwind v4 and `weapp-tailwindcss`.
+For H5 builds, keep a normal Vite `index.html`. The plugin injects the generated Taro H5 entry automatically.
 
-## Options
+```html
+<div id="app"></div>
+```
+
+## Plugin options
 
 ```ts
-type TaroTarget = 'wx' | 'h5'
+type VitePluginTaroTarget = 'wx' | 'h5'
 
-type TaroPageOption = {
+type VitePluginTaroPageOption = {
     path: string
     config: Record<string, unknown>
 }
 
-interface TaroPluginOptions {
-    target: TaroTarget
+type VitePluginTaroOptions = {
+    target: VitePluginTaroTarget
     app: string
-    pages: TaroPageOption[]
+    pages: VitePluginTaroPageOption[]
     appJson: Record<string, unknown>
     projectConfigJson: Record<string, unknown>
     sitemapJson: Record<string, unknown>
@@ -117,33 +162,35 @@ interface TaroPluginOptions {
 
 | Option | Description |
 | --- | --- |
-| `target` | Active build target: `wx` or `h5`. |
+| `target` | Active target for this Vite invocation: `h5` or `wx`. |
 | `app` | Source file that default-exports the root React app component. |
-| `pages` | Ordered page list. Also becomes `app.json.pages` and H5 route order. |
-| `appJson` | Base `app.json` content. `pages` is overwritten from `pages`. |
-| `projectConfigJson` | `project.config.json` emitted for WeChat builds. |
-| `sitemapJson` | `sitemap.json` emitted for WeChat builds. |
+| `pages` | Ordered page list. The order becomes `app.json.pages` and the H5 route order. |
+| `pages[].path` | Taro-style route and output path without extension, for example `pages/index/index`. The page component must exist at `src/${path}.tsx`. |
+| `pages[].config` | Page JSON config merged into WeChat page JSON and H5 route config. |
+| `appJson` | Base app config. The plugin overwrites `pages` from `options.pages`. |
+| `projectConfigJson` | WeChat `project.config.json` content emitted for `wx` builds. |
+| `sitemapJson` | WeChat `sitemap.json` content emitted for `wx` builds. |
 
-## App virtual modules
+## Scripts in your app
 
-| Import | Purpose |
-| --- | --- |
-| `virtual:taro` | Default-only Taro API facade. Use this instead of importing `@tarojs/taro` directly. |
-| `virtual:taro/components` | Re-export of `@tarojs/components`. Use this in app code. |
+Use separate scripts or environment files to build each target.
 
-## Package exports
+```json
+{
+    "scripts": {
+        "dev:h5": "VITE_PLUGIN_TARO_TARGET=h5 vite",
+        "build:h5": "VITE_PLUGIN_TARO_TARGET=h5 vite build",
+        "dev:wx": "VITE_PLUGIN_TARO_TARGET=wx vite build --watch",
+        "build:wx": "VITE_PLUGIN_TARO_TARGET=wx vite build"
+    }
+}
+```
 
-| Import | Purpose |
-| --- | --- |
-| `vite-plugin-taro` | Default Vite plugin entry. |
-| `vite-plugin-taro/vite` | Default Vite plugin entry. |
-| `vite-plugin-taro/client` | Type declarations for `virtual:taro` and `virtual:taro/components`. |
-| `vite-plugin-taro/shim/h5` | H5 runtime shim used by generated entries. |
-| `vite-plugin-taro/shim/wx` | WeChat runtime shim used by generated entries. |
+On Windows shells, use `cross-env` or your package manager's environment-file support.
 
 ## Conditional compilation
 
-vite-plugin-taro strips inactive Taro-style conditional comment blocks before Vite parses source files. Supported files include TypeScript, JavaScript, JSX/TSX, CSS, Sass, Less, and Stylus.
+The plugin strips inactive Taro-style conditional comment blocks before Vite parses source files. Supported source types include TypeScript, JavaScript, JSX/TSX, CSS, Sass, Less, and Stylus.
 
 ```ts
 // #ifdef wx
@@ -163,62 +210,67 @@ console.log('fallback')
 // #endif
 ```
 
-Supported directives are `#ifdef`, `#ifndef`, `#if`, `#elif`, `#else`, and `#endif`. Expressions support simple target tokens with `!`, `&&`, and `||`.
+Supported directives are `#ifdef`, `#ifndef`, `#if`, `#elif`, `#else`, and `#endif`. Expressions support target tokens with `!`, `&&`, and `||`.
 
-## Target output
-
-### `wx`
+## Styling
 
-vite-plugin-taro configures Rolldown for WeChat-compatible CommonJS chunks and emits Mini Program assets including:
+- H5 builds use `@tailwindcss/vite`.
+- WeChat builds use `weapp-tailwindcss` with Tailwind CSS v4 support, `px`/`rem` to `rpx` conversion, and WeChat-compatible selector output.
+- CSS emitted by Vite for `wx` is collected into `app.wxss`; page-level `.wxss` files are emitted as companions.
+- Import global styles from the app component, for example `import './app.css'`.
 
-- `app.js`, `app.json`, `app.wxss`.
-- Page `*.js`, `*.json`, `*.wxml`, and `*.wxss` files.
-- Shared Taro recursive template assets: `base.wxml`, `comp.js`, `comp.json`, `comp.wxml`, `utils.wxs`.
-- `project.config.json` and `sitemap.json`.
+## Target outputs
 
 ### `h5`
 
-vite-plugin-taro injects a virtual module into `index.html`, creates Taro H5 route records from `pages`, and mounts the app with Taro's hash-history router.
+The plugin injects a virtual module into `index.html`, imports Taro's component styles, creates H5 route records from `pages`, mounts the root app, and uses Taro's hash-history router.
 
-For GitHub Pages or any subpath deployment, set a relative/base path in Vite, for example:
+Typical output directory:
 
-```ts
-export default defineConfig({
-    base: './'
-})
+```text
+dist/h5/
 ```
 
-## React 19 compatibility
-
-Taro 4.2's official React runtime targets React 18. vite-plugin-taro depends on two small React 19-compatible runtime packages generated from the official Taro npm tarballs plus local patch files:
-
-- `vite-plugin-taro-react`
-- `vite-plugin-taro-plugin-framework-react`
-
-When packed/published by pnpm, workspace aliases become npm aliases to these patched packages:
+### `wx`
 
-```json
-{
-    "@tarojs/react": "npm:vite-plugin-taro-react@4.2.0-react19.2",
-    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@4.2.0-react19.2"
-}
+The plugin configures Rolldown for WeChat-compatible CommonJS chunks and emits Mini Program companion files.
+
+Typical output directory:
+
+```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/**
 ```
 
-That means app users get React 19-compatible Taro runtime packages automatically and do not need local patches.
+Open the `wx` output directory with WeChat DevTools.
 
-## Publishing from this repository
+## Limitations
 
-```sh
-pnpm install
-pnpm publish:dry
-pnpm publish:all
+- Supported targets are currently `h5` and WeChat Mini Program (`wx`). Other Taro platforms are not generated by this plugin.
+- Page modules follow the fixed convention `src/${page.path}.tsx`.
+- `projectConfigJson` and `sitemapJson` are required by the option type even though they are only emitted for `wx` builds.
+- Import Taro APIs/components through `vite-plugin-taro/taro` and `vite-plugin-taro/components`; direct `@tarojs/*` imports can bypass target aliases.
 
-# If npm 2FA is enabled:
-pnpm publish:all -- --otp 123456
-```
+## Troubleshooting
 
-The package publishes built ESM JavaScript and `.d.ts` files from `dist`.
+| Problem | Check |
+| --- | --- |
+| `VITE_PLUGIN_TARO_TARGET must be "h5" or "wx"` | Set the target environment variable before running Vite. |
+| A page cannot be resolved | Confirm that `pages[].path` has a matching `src/${path}.tsx` file. |
+| H5 component styles load in the wrong order | Make sure the plugin is registered and `vite-plugin-taro/components` is used for components. |
+| WeChat DevTools cannot open the project | Check `projectConfigJson.appid` and open the generated `dist/wx` directory, not the source package. |
+| Taro APIs behave differently per target | Import from `vite-plugin-taro/taro` so the plugin can apply target-specific runtime aliases and H5 API transforms. |
 
 ## License
 
-MIT.
+MIT. See [`LICENSE`](LICENSE).

package/dist/public/components.js

@@ -0,0 +1 @@
+export * from '@tarojs/components';

package/dist/public/taro.js

@@ -0,0 +1,8 @@
+import { hooks } from '@tarojs/runtime';
+import Taro from '@tarojs/taro';
+if (hooks.isExist('initNativeApi')) {
+    hooks.call('initNativeApi', Taro);
+}
+// @ts-expect-error @tarojs/taro declares export= types, but vite-plugin-taro target aliases expose runtime named exports.
+export * from '@tarojs/taro';
+export default Taro;

package/dist/shim/h5.js

@@ -1,5 +1,4 @@
 import '@tarojs/plugin-platform-h5/dist/runtime';
-import '@tarojs/components/global.css';
 // @ts-expect-error Taro exposes createReactApp from this runtime-only deep entry without types.
 export { createReactApp } from '@tarojs/plugin-framework-react/dist/runtime';
 export { createBrowserHistory, createHashHistory, createRouter, handleAppMount } from '@tarojs/router';

package/dist/vite/plugins.js

@@ -4,7 +4,7 @@ import { normalizeModuleId } from './utils.js';
  *
  * Mirrors Taro's CSS #ifdef/#ifndef handling, generalized before Vite parses code.
  */
-export function createTaroConditionalDirectivePlugin(context) {
+export function createVitePluginTaroConditionalDirectivePlugin(context) {
     const target = context.target;
     return {
         name: 'vite-plugin-taro-conditional-directives',
@@ -19,7 +19,7 @@ export function createTaroConditionalDirectivePlugin(context) {
 /**
  * Filters files where Taro's conditional comments are meaningful.
  *
- * vite-plugin-taro-only: source filter for vite-plugin-taro's generalized conditional-directive transform.
+ * Plugin-only: source filter for generalized conditional-directive transform.
  */
 function isConditionalDirectiveSource(id) {
     const normalizedId = normalizeModuleId(id);
@@ -85,7 +85,7 @@ function toConditionalDirectiveName(value) {
 /**
  * Updates the active conditional stack using Taro-style #ifdef/#ifndef/#else/#endif semantics.
  *
- * vite-plugin-taro-only: stack-based #if/#elif/#else support has no Taro webpack counterpart.
+ * Plugin-only: stack-based #if/#elif/#else support has no Taro webpack counterpart.
  */
 function updateConditionalDirectiveFrames(frames, directive, target) {
     if (directive.name === 'ifdef' || directive.name === 'ifndef' || directive.name === 'if') {
@@ -128,9 +128,9 @@ function evaluateConditionalDirective(directive, target) {
     return evaluateConditionalExpression(directive.expression, target);
 }
 /**
- * Supports simple #if expressions with !, &&, and || over vite-plugin-taro target tokens.
+ * Supports simple #if expressions with !, &&, and || over the configured target token.
  *
- * vite-plugin-taro-only: #if expressions with && and || have no Taro webpack counterpart.
+ * Plugin-only: #if expressions with && and || have no Taro webpack counterpart.
  */
 function evaluateConditionalExpression(expression, target) {
     const orTerms = expression.split('||');
@@ -141,9 +141,9 @@ function evaluateConditionalExpression(expression, target) {
         .every((factor) => evaluateConditionalFactor(factor, target)));
 }
 /**
- * Evaluates one vite-plugin-taro target token, optionally negated.
+ * Evaluates one target token, optionally negated.
  *
- * vite-plugin-taro-only: negated #if factors have no Taro webpack counterpart.
+ * Plugin-only: negated #if factors have no Taro webpack counterpart.
  */
 function evaluateConditionalFactor(factor, target) {
     let token = factor.replace(/[()]/g, '').trim();
@@ -156,7 +156,7 @@ function evaluateConditionalFactor(factor, target) {
     return negated ? !matched : matched;
 }
 /**
- * Checks whether a directive target list includes the current vite-plugin-taro target.
+ * Checks whether a directive target list includes the current target.
  *
  * Mirrors Taro's simple CSS platform membership checks.
  */
@@ -170,7 +170,7 @@ function matchesDirectiveTarget(expression, target) {
 /**
  * Preserves source line counts when conditional blocks are stripped.
  *
- * vite-plugin-taro-only: preserves Vite source-map line counts while stripping conditional blocks.
+ * Plugin-only: preserves Vite source-map line counts while stripping conditional blocks.
  */
 function getLineEnding(line) {
     const match = line.match(/\r?\n$/);
@@ -179,7 +179,7 @@ function getLineEnding(line) {
 /**
  * Returns whether all active nested conditional frames include the current line.
  *
- * vite-plugin-taro-only: stack activity helper for generalized conditional directives.
+ * Plugin-only: stack activity helper for generalized conditional directives.
  */
 function isDirectiveStackActive(frames) {
     return frames.every((frame) => frame.active);

package/dist/vite/tailwindcss.js

@@ -0,0 +1,35 @@
+import tailwindcss from '@tailwindcss/vite';
+import { WeappTailwindcss } from 'weapp-tailwindcss/vite';
+export function createTailwindcssPlugins(context) {
+    if (context.target === 'h5')
+        return [tailwindcss()];
+    const plugins = WeappTailwindcss({
+        appType: 'taro',
+        generator: {
+            target: 'weapp'
+        },
+        tailwindcss: {
+            version: 4,
+            packageName: 'tailwindcss'
+        },
+        cssCalc: false,
+        // skyline does not support -webkit prefix.
+        autoprefixer: false,
+        postcssOptions: {
+            // Tailwind v4 prod mode emits legacy :before/:after selectors; skyline requires ::before/::after.
+            plugins: [createWechatPseudoElementPlugin()]
+        },
+        rem2rpx: true,
+        px2rpx: true
+    });
+    return plugins ?? [];
+}
+function createWechatPseudoElementPlugin() {
+    const legacyPseudoElementPattern = /(?<!:):(before|after)\b/g;
+    return {
+        postcssPlugin: 'vite-plugin-taro-wechat-pseudo-elements',
+        Rule(rule) {
+            rule.selector = rule.selector.replace(legacyPseudoElementPattern, '::$1');
+        }
+    };
+}

package/dist/vite/targets/h5.js

@@ -3,6 +3,7 @@ import react from '@vitejs/plugin-react';
 import { isProd, nodeRequire } from '../constants.js';
 import { createPageComponentImport } from '../utils.js';
 const virtualH5Id = 'virtual:vite-plugin-taro/h5';
+const patchStencilCssOrder = true;
 /**
  * Checks whether an id belongs to an H5 virtual module.
  */
@@ -26,6 +27,17 @@ export function createH5ViteConfig() {
         resolve: {
             mainFields: ['main:h5', 'browser', 'module', 'jsnext:main', 'jsnext'],
             alias: [
+                // Resolve Stencil's transitive runtime import after Taro components are optimized separately.
+                ...(patchStencilCssOrder
+                    ? [
+                        {
+                            find: /^@stencil\/core\/internal\/client$/,
+                            replacement: nodeRequire.resolve('@stencil/core/internal/client', {
+                                paths: [nodeRequire.resolve('@tarojs/components/package.json')]
+                            })
+                        }
+                    ]
+                    : []),
                 // H5 React code must use Taro's React component wrappers, not the raw custom-element entry.
                 { find: /^@tarojs\/components$/, replacement: nodeRequire.resolve('@tarojs/components/lib/react') },
                 // Taro's H5 router/components deep-import this custom-element loader; make it resolvable under pnpm.
@@ -40,6 +52,10 @@ export function createH5ViteConfig() {
                 }
             ]
         },
+        optimizeDeps: {
+            // Keep the Stencil runtime in Vite's transform pipeline so rewriteStencilStyleInsertion can patch it.
+            exclude: [patchStencilCssOrder ? '@stencil/core/internal/client' : ''].filter(Boolean)
+        },
         build: {
             target: 'es2018',
             minify: isProd
@@ -52,21 +68,44 @@ export function createH5ViteConfig() {
  * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-platform-h5/src/program.ts#L219-L249
  */
 export function createH5SupportPlugins() {
-    return [
-        ...react(),
-        // Mirrors Taro H5: rewrite default Taro.xxx calls from virtual:taro to named H5 API imports.
-        babel({
-            plugins: [
-                [
-                    nodeRequire.resolve('babel-plugin-transform-taroapi'),
-                    {
-                        packageName: 'virtual:taro',
-                        definition: nodeRequire(nodeRequire.resolve('@tarojs/plugin-platform-h5/dist/definition.json'))
-                    }
-                ]
+    const plugins = [...react()];
+    if (patchStencilCssOrder) {
+        plugins.push(babel({
+            include: /[\\/]@stencil[\\/]core[\\/]internal[\\/]client[\\/]index\.js(?:\?.*)?$/,
+            exclude: [],
+            plugins: [rewriteStencilStyleInsertion]
+        }));
+    }
+    // Mirrors Taro H5: rewrite default Taro.xxx calls from vite-plugin-taro/taro to named H5 API imports.
+    plugins.push(babel({
+        plugins: [
+            [
+                nodeRequire.resolve('babel-plugin-transform-taroapi'),
+                {
+                    packageName: 'vite-plugin-taro/taro',
+                    definition: nodeRequire(nodeRequire.resolve('@tarojs/plugin-platform-h5/dist/definition.json'))
+                }
             ]
-        })
-    ];
+        ]
+    }));
+    return plugins;
+}
+function rewriteStencilStyleInsertion() {
+    return {
+        name: 'rewrite-stencil-style-insertion',
+        visitor: {
+            CallExpression(path) {
+                if (!isStencilStyleInsertBeforeCall(path))
+                    return;
+                path.get('arguments.1').replaceWithSourceString(`scopeId.startsWith('sc-taro-') ? styleContainerNode.querySelector('style,link[rel="stylesheet"]') : styleContainerNode.querySelector('link')`);
+            }
+        }
+    };
+}
+function isStencilStyleInsertBeforeCall(path) {
+    return (path.get('callee').matchesPattern('styleContainerNode.insertBefore') &&
+        path.get('arguments.0').toString() === 'styleElm' &&
+        path.get('arguments.1').toString() === "styleContainerNode.querySelector('link')");
 }
 /**
  * Creates compile-time constants expected by Taro's Web runtime packages.
@@ -102,14 +141,16 @@ export function createWebIndexHtmlTags(context) {
 }
 /**
  * Builds the generated Web entry around Taro's official Web router/runtime APIs.
- * vite-plugin-taro omits Taro's generated pxTransform initialization; apps should handle style transforms in their own Vite pipeline.
+ * Base Taro CSS is imported before the app; component CSS order is handled by rewriteStencilStyleInsertion.
  *
  * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-loader/src/h5.ts#L120-L150
  */
 export function createWebEntry(context) {
     const webAppConfigCode = JSON.stringify(createWebAppConfig(context.appConfig));
     const webRoutesConfigCode = createWebRoutesConfig(context.pages);
-    return `import {
+    return `import ${JSON.stringify(nodeRequire.resolve('@tarojs/components/global.css'))}
+import ${JSON.stringify(nodeRequire.resolve('@tarojs/components/dist/taro-components/taro-components.css'))}
+import {
     createHashHistory,
     createReactApp,
     createRouter,

package/dist/vite/targets/wx.js

@@ -29,7 +29,7 @@ export function loadWxVirtualModule(cleanId, context) {
     }
 }
 const taroWechatComponentsReactPath = nodeRequire.resolve('@tarojs/plugin-platform-weapp/dist/components-react');
-const pluginSourcePath = normalizeModuleId(path.dirname(nodeRequire.resolve('vite-plugin-taro/vite')));
+const vitePluginTaroSourcePath = normalizeModuleId(path.dirname(nodeRequire.resolve('vite-plugin-taro/vite')));
 const taroVersion = String(nodeRequire('@tarojs/runtime/package.json').version);
 /**
  * Configures wx target entry, output, and chunk layout.
@@ -107,9 +107,7 @@ function createWechatTaroDefines() {
  */
 function isWxTaroChunkModule(id) {
     const normalizedId = normalizeModuleId(id);
-    return (normalizedId.includes('/node_modules/@tarojs/') ||
-        normalizedId.startsWith(`${pluginSourcePath}/`) ||
-        normalizedId.includes('virtual:taro'));
+    return normalizedId.includes('/node_modules/@tarojs/') || normalizedId.startsWith(`${vitePluginTaroSourcePath}/`);
 }
 /**
  * Names Rolldown's helper chunk like Taro webpack's runtime chunk.
@@ -156,7 +154,7 @@ export function emitWechatImplicitChunksForVirtualApp(emitter, context, cleanId)
 }
 /**
  * Builds the generated WeChat app entry that registers Taro's React App config.
- * vite-plugin-taro omits Taro's generated pxTransform initialization; apps should handle style transforms in their own Vite pipeline.
+ * vite-plugin-taro omits Taro's generated pxTransform initialization because styles are handled by Tailwind.
  *
  * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-loader/src/app.ts#L54-L63
  */