vite-plugin-taro 0.0.2 → 0.0.4

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 felix
+Copyright (c) 2026 sep2
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,60 +1,196 @@
 # vite-plugin-taro
 
-Vite 8 + React 19 plugin for building one React/Taro codebase for both:
+[![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)
 
-- `wx`: WeChat Mini Program output.
-- `h5`: Web output powered by Taro H5 runtime and router.
+Vite 8 plugin for building one React 19 + Taro 4 app as either Web (`h5`) or WeChat Mini Program (`wx`).
 
-It wraps React 19-compatible Taro runtime packages, emits the generated app/page entries that Taro normally creates, and configures Vite/Rolldown, Tailwind CSS, and target-specific aliases for the selected target.
+## Highlights
+
+- 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, { type TaroTarget } 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 TaroTarget
+    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: 'touristappid' },
-                sitemapJson: { rules: [{ action: 'allow', page: '*' }] }
+                projectConfigJson: {
+                    appid: env.VITE_PLUGIN_TARO_WECHAT_APP_ID || 'touristappid'
+                },
+                sitemapJson: {
+                    rules: [{ action: 'allow', page: '*' }]
+                }
             })
         ]
     }
 })
 ```
 
-Application code should usually import only `vite-plugin-taro/components` and `vite-plugin-taro/taro`.
+### App component
 
-## Package exports
+`app` points to a module that default-exports the root React app component.
+
+```tsx
+// src/app.ts
+import type { PropsWithChildren } from 'react'
+import Taro from 'vite-plugin-taro/taro'
+import './app.css'
+
+export default function App({ children }: PropsWithChildren) {
+    Taro.useLaunch(() => {
+        console.log('App launch')
+    })
+
+    return children
+}
+```
+
+### Page component
+
+Each `pages[].path` maps to `src/${path}.tsx`.
+
+```tsx
+// src/pages/index/index.tsx
+import { Text, View } from 'vite-plugin-taro/components'
+import Taro from 'vite-plugin-taro/taro'
+
+export default function IndexPage() {
+    const windowInfo = Taro.getWindowInfo()
+
+    return (
+        <View>
+            <Text>Viewport width: {windowInfo.windowWidth}</Text>
+        </View>
+    )
+}
+```
+
+### HTML shell for H5
+
+For H5 builds, keep a normal Vite `index.html`. The plugin injects the generated Taro H5 entry automatically.
+
+```html
+<div id="app"></div>
+```
 
-| Import | Purpose |
+## Plugin 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 |
 | --- | --- |
-| `vite-plugin-taro` | Default Vite plugin and public plugin types. |
-| `vite-plugin-taro/vite` | Default Vite plugin and `TaroTarget`, `TaroPluginOptions`, `TaroPageOption` types. |
-| `vite-plugin-taro/components` | Re-export of `@tarojs/components`. Use this in app code. |
-| `vite-plugin-taro/taro` | Taro API facade. Use this instead of importing `@tarojs/taro` directly. |
-| `vite-plugin-taro/shim/h5` | H5 runtime shim used by generated entries. |
-| `vite-plugin-taro/shim/wx` | WeChat runtime shim used by generated entries. |
+| `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. 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. |
+
+## Scripts in your app
+
+Use separate scripts or environment files to build each target.
+
+```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"
+    }
+}
+```
+
+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
@@ -74,52 +210,67 @@ console.log('fallback')
 // #endif
 ```
 
-Supported directives are `#ifdef`, `#ifndef`, `#if`, `#elif`, `#else`, and `#endif`. Expressions support simple target tokens with `!`, `&&`, and `||`.
-
-## Target output
+Supported directives are `#ifdef`, `#ifndef`, `#if`, `#elif`, `#else`, and `#endif`. Expressions support target tokens with `!`, `&&`, and `||`.
 
-### `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.
-
-## React 19 compatibility
+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.
 
-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 vite-plugin-taro's local patch files:
+Typical output directory:
 
-- `vite-plugin-taro-react`
-- `vite-plugin-taro-plugin-framework-react`
+```text
+dist/h5/
+```
 
-In the workspace these are referenced with pnpm workspace aliases:
+### `wx`
 
-```json
-{
-    "@tarojs/react": "workspace:vite-plugin-taro-react@*",
-    "@tarojs/plugin-framework-react": "workspace:vite-plugin-taro-plugin-framework-react@*"
-}
+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/**
 ```
 
-When packed/published by pnpm, those become npm aliases to the published patched packages. vite-plugin-taro source can keep importing the upstream Taro specifiers while users receive the patched React 19-compatible packages automatically.
+Open the `wx` output directory with WeChat DevTools.
 
-Run `pnpm prepare:taro` to regenerate the patched packages from upstream tarballs. Publish those runtime packages before publishing `vite-plugin-taro`.
+## Limitations
 
-## Publishing
+- 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.
 
-```sh
-pnpm install
-pnpm publish:dry
-pnpm publish:all
+## Troubleshooting
 
-# If npm 2FA is enabled:
-pnpm publish:all -- --otp 123456
-```
+| 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
 
-The package publishes built ESM JavaScript and `.d.ts` files from `dist`.
+MIT. See [`LICENSE`](LICENSE).

package/dist/public/components.js

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

package/dist/public/taro.js

@@ -1,10 +1,8 @@
-import { hooks } from "@tarojs/runtime";
-import Taro from "@tarojs/taro";
-export * from "@tarojs/taro";
-//#region src/public/taro.ts
-if (hooks.isExist("initNativeApi")) hooks.call("initNativeApi", Taro);
-var taro_default = Taro;
-//#endregion
-export { taro_default as default };
-
-//# sourceMappingURL=taro.js.map
+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,6 +1,5 @@
-import { window } from "@tarojs/runtime";
-import "@tarojs/plugin-platform-h5/dist/runtime";
-import "@tarojs/components/global.css";
-import { createReactApp } from "@tarojs/plugin-framework-react/dist/runtime";
-import { createBrowserHistory, createHashHistory, createRouter, handleAppMount } from "@tarojs/router";
-export { createBrowserHistory, createHashHistory, createReactApp, createRouter, handleAppMount, window };
+import '@tarojs/plugin-platform-h5/dist/runtime';
+// @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';
+export { window } from '@tarojs/runtime';

package/dist/shim/wx.js

@@ -1,5 +1,5 @@
-import { createPageConfig, createRecursiveComponentConfig } from "@tarojs/runtime";
-import { createReactApp } from "@tarojs/plugin-framework-react/dist/runtime";
-import "@tarojs/plugin-platform-weapp/dist/runtime.js";
-import ReactDOM from "@tarojs/react";
-export { ReactDOM, createPageConfig, createReactApp, createRecursiveComponentConfig };
+import '@tarojs/plugin-platform-weapp/dist/runtime.js';
+// @ts-expect-error Taro exposes createReactApp from this runtime-only deep entry without types.
+export { createReactApp } from '@tarojs/plugin-framework-react/dist/runtime';
+export { default as ReactDOM } from '@tarojs/react';
+export { createPageConfig, createRecursiveComponentConfig } from '@tarojs/runtime';

package/dist/vite/constants.js

@@ -0,0 +1,3 @@
+import { createRequire } from 'node:module';
+export const isProd = process.env.NODE_ENV === 'production';
+export const nodeRequire = createRequire(import.meta.url);

package/dist/vite/plugins.js

@@ -0,0 +1,186 @@
+import { normalizeModuleId } from './utils.js';
+/**
+ * Applies Taro-style conditional compilation comments before Vite parses source files.
+ *
+ * Mirrors Taro's CSS #ifdef/#ifndef handling, generalized before Vite parses code.
+ */
+export function createVitePluginTaroConditionalDirectivePlugin(context) {
+    const target = context.target;
+    return {
+        name: 'vite-plugin-taro-conditional-directives',
+        enforce: 'pre',
+        transform(code, id) {
+            if (!isConditionalDirectiveSource(id) || !code.includes('#if'))
+                return;
+            return { code: transformConditionalDirectives(code, target), map: null };
+        }
+    };
+}
+/**
+ * Filters files where Taro's conditional comments are meaningful.
+ *
+ * Plugin-only: source filter for generalized conditional-directive transform.
+ */
+function isConditionalDirectiveSource(id) {
+    const normalizedId = normalizeModuleId(id);
+    if (normalizedId.includes('/node_modules/'))
+        return false;
+    return /\.(?:[cm]?[jt]sx?|css|s[ac]ss|less|styl)(?:\?|$)/.test(normalizedId);
+}
+/**
+ * Removes inactive blocks guarded by Taro conditional comments.
+ *
+ * Mirrors Taro's CSS #ifdef/#ifndef handling.
+ */
+function transformConditionalDirectives(code, target) {
+    const lines = code.match(/[^\n]*(?:\n|$)/g) ?? [];
+    const frames = [];
+    let transformed = '';
+    for (const line of lines) {
+        if (!line)
+            continue;
+        const directive = parseConditionalDirective(line);
+        const lineEnding = getLineEnding(line);
+        if (directive) {
+            updateConditionalDirectiveFrames(frames, directive, target);
+            transformed += lineEnding;
+            continue;
+        }
+        transformed += isDirectiveStackActive(frames) ? line : lineEnding;
+    }
+    return transformed;
+}
+/**
+ * Parses one Taro conditional compilation directive from a comment-only line.
+ *
+ * Mirrors Taro's CSS comment-token handling.
+ */
+function parseConditionalDirective(line) {
+    const match = line.match(/^\s*(?:(?:\/\/)|(?:\/\*))\s*#(ifdef|ifndef|if|elif|else|endif)\b([^*\r\n]*)/);
+    if (!match)
+        return;
+    const name = toConditionalDirectiveName(match[1]);
+    if (!name)
+        return;
+    return {
+        name,
+        expression: match[2]?.replace(/\*\/$/, '').trim() ?? ''
+    };
+}
+/**
+ * Converts a regex capture into a supported directive name.
+ *
+ * Mirrors Taro's CSS #ifdef/#ifndef/#endif token handling.
+ */
+function toConditionalDirectiveName(value) {
+    if (value === 'ifdef' ||
+        value === 'ifndef' ||
+        value === 'if' ||
+        value === 'elif' ||
+        value === 'else' ||
+        value === 'endif') {
+        return value;
+    }
+}
+/**
+ * Updates the active conditional stack using Taro-style #ifdef/#ifndef/#else/#endif semantics.
+ *
+ * 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') {
+        const conditionMatched = evaluateConditionalDirective(directive, target);
+        const parentActive = isDirectiveStackActive(frames);
+        frames.push({ parentActive, active: parentActive && conditionMatched, matched: conditionMatched });
+        return;
+    }
+    const currentFrame = frames.at(-1);
+    if (!currentFrame)
+        return;
+    if (directive.name === 'elif') {
+        if (currentFrame.matched) {
+            currentFrame.active = false;
+            return;
+        }
+        const conditionMatched = evaluateConditionalDirective(directive, target);
+        currentFrame.active = currentFrame.parentActive && conditionMatched;
+        currentFrame.matched = conditionMatched;
+        return;
+    }
+    if (directive.name === 'else') {
+        currentFrame.active = currentFrame.parentActive && !currentFrame.matched;
+        currentFrame.matched = true;
+        return;
+    }
+    if (directive.name === 'endif')
+        frames.pop();
+}
+/**
+ * Evaluates the small expression subset used by Taro conditional comments.
+ *
+ * Mirrors Taro's simple CSS platform membership checks.
+ */
+function evaluateConditionalDirective(directive, target) {
+    if (directive.name === 'ifndef')
+        return !matchesDirectiveTarget(directive.expression, target);
+    if (directive.name === 'ifdef')
+        return matchesDirectiveTarget(directive.expression, target);
+    return evaluateConditionalExpression(directive.expression, target);
+}
+/**
+ * Supports simple #if expressions with !, &&, and || over the configured target token.
+ *
+ * Plugin-only: #if expressions with && and || have no Taro webpack counterpart.
+ */
+function evaluateConditionalExpression(expression, target) {
+    const orTerms = expression.split('||');
+    return orTerms.some((term) => term
+        .split('&&')
+        .map((factor) => factor.trim())
+        .filter(Boolean)
+        .every((factor) => evaluateConditionalFactor(factor, target)));
+}
+/**
+ * Evaluates one target token, optionally negated.
+ *
+ * Plugin-only: negated #if factors have no Taro webpack counterpart.
+ */
+function evaluateConditionalFactor(factor, target) {
+    let token = factor.replace(/[()]/g, '').trim();
+    let negated = false;
+    while (token.startsWith('!')) {
+        negated = !negated;
+        token = token.slice(1).trim();
+    }
+    const matched = matchesDirectiveTarget(token, target);
+    return negated ? !matched : matched;
+}
+/**
+ * Checks whether a directive target list includes the current target.
+ *
+ * Mirrors Taro's simple CSS platform membership checks.
+ */
+function matchesDirectiveTarget(expression, target) {
+    const tokens = expression
+        .split(/[\s,|&()!]+/)
+        .map((token) => token.trim().toLowerCase())
+        .filter(Boolean);
+    return tokens.includes(target);
+}
+/**
+ * Preserves source line counts when conditional blocks are stripped.
+ *
+ * Plugin-only: preserves Vite source-map line counts while stripping conditional blocks.
+ */
+function getLineEnding(line) {
+    const match = line.match(/\r?\n$/);
+    return match?.[0] ?? '';
+}
+/**
+ * Returns whether all active nested conditional frames include the current line.
+ *
+ * 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');
+        }
+    };
+}