vite-plugin-taro 0.0.2 → 0.0.3

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,11 +1,19 @@
 # vite-plugin-taro
 
-Vite 8 + React 19 plugin for building one React/Taro codebase for both:
+Vite 8 + React 19 plugin for building one React/Taro codebase for both WeChat Mini Program (`wx`) and Web (`h5`) targets.
 
-- `wx`: WeChat Mini Program output.
-- `h5`: Web output powered by Taro H5 runtime and router.
+- 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>
 
-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.
+## Features
+
+- `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.
 
 ## Install
 
@@ -17,21 +25,24 @@ pnpm add react react-dom
 ## Vite usage
 
 ```ts
-import taro, { type TaroTarget } from 'vite-plugin-taro/vite'
+import taro from 'vite-plugin-taro/vite'
 import { defineConfig, loadEnv } from 'vite'
 
 export default defineConfig(({ mode }) => {
     const env = loadEnv(mode, process.cwd(), 'VITE_PLUGIN_TARO_')
-    const target = env.VITE_PLUGIN_TARO_TARGET as TaroTarget
+    const target = env.VITE_PLUGIN_TARO_TARGET as 'wx' | 'h5'
 
     return {
+        base: target === 'h5' ? './' : undefined,
         plugins: [
             taro({
                 target,
                 app: 'src/app.ts',
                 pages: [{ path: 'pages/index/index', config: {} }],
                 appJson: {},
-                projectConfigJson: { appid: 'touristappid' },
+                projectConfigJson: {
+                    appid: env.VITE_PLUGIN_TARO_WECHAT_APP_ID || 'touristappid'
+                },
                 sitemapJson: { rules: [{ action: 'allow', page: '*' }] }
             })
         ]
@@ -39,16 +50,94 @@ export default defineConfig(({ mode }) => {
 })
 ```
 
-Application code should usually import only `vite-plugin-taro/components` and `vite-plugin-taro/taro`.
+Example scripts:
+
+```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"
+    }
+}
+```
+
+Application code should usually import only from the plugin virtual modules. `virtual:taro` is default-export only; call APIs as `Taro.xxx`.
+
+```ts
+import Taro from 'virtual:taro'
+import { Text, View } from 'virtual:taro/components'
+
+Taro.useLaunch(() => {})
+Taro.getWindowInfo()
+```
+
+For Taro namespace types:
+
+```ts
+import type Taro from 'virtual:taro'
+
+type Color = Taro.Color
+```
+
+Add the virtual module declarations to the app `tsconfig.json`:
+
+```json
+{
+    "compilerOptions": {
+        "types": ["vite/client", "vite-plugin-taro/client"]
+    }
+}
+```
+
+## Styling
+
+`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`.
+
+## Options
+
+```ts
+type TaroTarget = 'wx' | 'h5'
+
+type TaroPageOption = {
+    path: string
+    config: Record<string, unknown>
+}
+
+interface TaroPluginOptions {
+    target: TaroTarget
+    app: string
+    pages: TaroPageOption[]
+    appJson: Record<string, unknown>
+    projectConfigJson: Record<string, unknown>
+    sitemapJson: Record<string, unknown>
+}
+```
+
+| Option | Description |
+| --- | --- |
+| `target` | Active build target: `wx` or `h5`. |
+| `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. |
+
+## App virtual modules
+
+| 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. |
 
 ## Package exports
 
 | Import | Purpose |
 | --- | --- |
-| `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` | 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. |
 
@@ -91,27 +180,33 @@ vite-plugin-taro configures Rolldown for WeChat-compatible CommonJS chunks and e
 
 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.
 
+For GitHub Pages or any subpath deployment, set a relative/base path in Vite, for example:
+
+```ts
+export default defineConfig({
+    base: './'
+})
+```
+
 ## 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 vite-plugin-taro's local patch files:
+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`
 
-In the workspace these are referenced with pnpm workspace aliases:
+When packed/published by pnpm, workspace aliases become npm aliases to these patched packages:
 
 ```json
 {
-    "@tarojs/react": "workspace:vite-plugin-taro-react@*",
-    "@tarojs/plugin-framework-react": "workspace:vite-plugin-taro-plugin-framework-react@*"
+    "@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"
 }
 ```
 
-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.
+That means app users get React 19-compatible Taro runtime packages automatically and do not need local patches.
 
-Run `pnpm prepare:taro` to regenerate the patched packages from upstream tarballs. Publish those runtime packages before publishing `vite-plugin-taro`.
-
-## Publishing
+## Publishing from this repository
 
 ```sh
 pnpm install
@@ -123,3 +218,7 @@ pnpm publish:all -- --otp 123456
 ```
 
 The package publishes built ESM JavaScript and `.d.ts` files from `dist`.
+
+## License
+
+MIT.

package/client.d.ts

@@ -0,0 +1,10 @@
+declare module 'virtual:taro' {
+    import Taro = require('@tarojs/taro')
+
+    const taro: typeof Taro
+    export default taro
+}
+
+declare module 'virtual:taro/components' {
+    export * from '@tarojs/components'
+}

package/dist/shim/h5.js

@@ -1,6 +1,6 @@
-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';
+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';
+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 createTaroConditionalDirectivePlugin(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.
+ *
+ * vite-plugin-taro-only: source filter for vite-plugin-taro's 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.
+ *
+ * vite-plugin-taro-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 vite-plugin-taro target tokens.
+ *
+ * vite-plugin-taro-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 vite-plugin-taro target token, optionally negated.
+ *
+ * vite-plugin-taro-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 vite-plugin-taro 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.
+ *
+ * vite-plugin-taro-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.
+ *
+ * vite-plugin-taro-only: stack activity helper for generalized conditional directives.
+ */
+function isDirectiveStackActive(frames) {
+    return frames.every((frame) => frame.active);
+}

package/dist/vite/targets/h5.js

@@ -0,0 +1,161 @@
+import babel from '@rolldown/plugin-babel';
+import react from '@vitejs/plugin-react';
+import { isProd, nodeRequire } from '../constants.js';
+import { createPageComponentImport } from '../utils.js';
+const virtualH5Id = 'virtual:vite-plugin-taro/h5';
+/**
+ * Checks whether an id belongs to an H5 virtual module.
+ */
+export function isH5VirtualModuleId(id) {
+    return id === virtualH5Id;
+}
+/**
+ * Loads generated source for H5 virtual modules.
+ */
+export function loadH5VirtualModule(cleanId, context) {
+    if (cleanId !== virtualH5Id)
+        return;
+    return createWebEntry(context);
+}
+/**
+ * Configures the Vite pieces needed for Taro H5 resolve/runtime behavior.
+ */
+export function createH5ViteConfig() {
+    return {
+        define: createH5TaroDefines(),
+        resolve: {
+            mainFields: ['main:h5', 'browser', 'module', 'jsnext:main', 'jsnext'],
+            alias: [
+                // 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.
+                {
+                    find: /^@tarojs\/components\/dist\/components$/,
+                    replacement: nodeRequire.resolve('@tarojs/components/dist/components')
+                },
+                // H5 APIs are exported from the platform API barrel; the generic @tarojs/taro root is native-oriented.
+                {
+                    find: /^@tarojs\/taro$/,
+                    replacement: nodeRequire.resolve('@tarojs/plugin-platform-h5/dist/runtime/apis')
+                }
+            ]
+        },
+        build: {
+            target: 'es2018',
+            minify: isProd
+        }
+    };
+}
+/**
+ * Creates H5-only support plugins used before the target emitter runs.
+ *
+ * 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'))
+                    }
+                ]
+            ]
+        })
+    ];
+}
+/**
+ * Creates compile-time constants expected by Taro's Web runtime packages.
+ *
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-webpack5-runner/src/webpack/H5WebpackPlugin.ts#L51-L69
+ */
+function createH5TaroDefines() {
+    return {
+        'process.env.FRAMEWORK': JSON.stringify('react'),
+        'process.env.SUPPORT_TARO_POLYFILL': JSON.stringify('disabled'),
+        'process.env.TARO_ENV': JSON.stringify('h5'),
+        'process.env.TARO_PLATFORM': JSON.stringify('web'),
+        IS_H5: 'true',
+        IS_WEAPP: 'false',
+        'process.env.SUPPORT_DINGTALK_NAVIGATE': JSON.stringify('disabled'),
+        DEPRECATED_ADAPTER_COMPONENT: 'false'
+    };
+}
+/**
+ * Injects vite-plugin-taro's generated Web entry into Vite's HTML shell.
+ */
+export function createWebIndexHtmlTags(context) {
+    if (context.target !== 'h5')
+        return;
+    const tags = [];
+    tags.push({
+        tag: 'script',
+        attrs: { type: 'module' },
+        children: `import '${virtualH5Id}'`,
+        injectTo: 'body'
+    });
+    return tags;
+}
+/**
+ * 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.
+ *
+ * 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 {
+    createHashHistory,
+    createReactApp,
+    createRouter,
+    handleAppMount,
+    window
+} from 'vite-plugin-taro/shim/h5'
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import AppComponent from '${context.appComponentImport}'
+
+const config = window.__taroAppConfig = ${webAppConfigCode}
+config.routes = ${webRoutesConfigCode}
+const app = createReactApp(AppComponent, React, ReactDOM, config)
+const history = createHashHistory({ window })
+handleAppMount(config, history)
+createRouter(history, app, config, React)
+`;
+}
+/**
+ * Creates the H5 app config consumed by Taro's Web router.
+ * Taro's H5 runtime expects `config.router` to exist, even when it is an empty object.
+ *
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-webpack5-runner/src/plugins/H5Plugin.ts#L49-L53
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-webpack5-runner/src/plugins/H5Plugin.ts#L133-L138
+ */
+function createWebAppConfig(sharedAppConfig) {
+    return {
+        router: {},
+        ...sharedAppConfig
+    };
+}
+/**
+ * Creates Web route records in the same shape as Taro's H5 loader.
+ *
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-loader/src/h5.ts#L12-L21
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-loader/src/h5.ts#L108-L114
+ */
+function createWebRoutesConfig(webPages) {
+    const webRoutes = webPages.map((page) => [
+        'Object.assign({',
+        `  path: ${JSON.stringify(page.path)},`,
+        '  load: async function(context, params) {',
+        `    const page = await import(${JSON.stringify(createPageComponentImport(page.path))})`,
+        '    return [page, context, params]',
+        '  }',
+        `}, ${JSON.stringify(page.config)})`
+    ].join('\n'));
+    return `[\n${webRoutes.join(',\n')}\n]`;
+}