vite-plugin-taro 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 felix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# vite-plugin-taro
+
+Vite 8 + React 19 plugin for building one React/Taro codebase for both:
+
+- `wx`: WeChat Mini Program output.
+- `h5`: Web output powered by Taro H5 runtime and router.
+
+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.
+
+## Install
+
+```sh
+pnpm add -D vite-plugin-taro vite
+pnpm add react react-dom
+```
+
+## Vite usage
+
+```ts
+import taro, { type TaroTarget } 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
+
+    return {
+        plugins: [
+            taro({
+                target,
+                app: 'src/app.ts',
+                pages: [{ path: 'pages/index/index', config: {} }],
+                appJson: {},
+                projectConfigJson: { appid: 'touristappid' },
+                sitemapJson: { rules: [{ action: 'allow', page: '*' }] }
+            })
+        ]
+    }
+})
+```
+
+Application code should usually import only `vite-plugin-taro/components` and `vite-plugin-taro/taro`.
+
+## 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/shim/h5` | H5 runtime shim used by generated entries. |
+| `vite-plugin-taro/shim/wx` | WeChat runtime shim used by generated entries. |
+
+## 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.
+
+```ts
+// #ifdef wx
+console.log('WeChat only')
+// #endif
+
+// #ifdef h5
+console.log('H5 only')
+// #endif
+
+// #if h5 && !wx
+console.log('H5 expression')
+// #elif wx
+console.log('WeChat expression')
+// #else
+console.log('fallback')
+// #endif
+```
+
+Supported directives are `#ifdef`, `#ifndef`, `#if`, `#elif`, `#else`, and `#endif`. Expressions support simple target tokens with `!`, `&&`, and `||`.
+
+## Target output
+
+### `wx`
+
+vite-plugin-taro configures Rolldown for WeChat-compatible CommonJS chunks and emits Mini Program assets including:
+
+- `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`.
+
+### `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
+
+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:
+
+- `vite-plugin-taro-react`
+- `vite-plugin-taro-plugin-framework-react`
+
+In the workspace these are referenced with pnpm workspace aliases:
+
+```json
+{
+    "@tarojs/react": "workspace:vite-plugin-taro-react@*",
+    "@tarojs/plugin-framework-react": "workspace:vite-plugin-taro-plugin-framework-react@*"
+}
+```
+
+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.
+
+Run `pnpm prepare:taro` to regenerate the patched packages from upstream tarballs. Publish those runtime packages before publishing `vite-plugin-taro`.
+
+## Publishing
+
+```sh
+pnpm install
+pnpm prepare:taro
+pnpm --filter vite-plugin-taro-react pack --dry-run
+pnpm --filter vite-plugin-taro-plugin-framework-react pack --dry-run
+pnpm --filter vite-plugin-taro typecheck
+pnpm --filter vite-plugin-taro build
+pnpm --filter vite-plugin-taro pack:dry
+```
+
+The package publishes built ESM JavaScript and `.d.ts` files from `dist`.

package/dist/public/components.d.ts

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

package/dist/public/components.js

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

package/dist/public/taro.d.ts

@@ -0,0 +1,2 @@
+import Taro = require('@tarojs/taro')
+export = Taro

package/dist/public/taro.js

@@ -0,0 +1,10 @@
+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

package/dist/public/taro.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"taro.js","names":[],"sources":["../../src/public/taro.ts"],"sourcesContent":["import { hooks } from '@tarojs/runtime'\nimport Taro from '@tarojs/taro'\n\nif (hooks.isExist('initNativeApi')) {\n    hooks.call('initNativeApi', Taro)\n}\n\n// @ts-expect-error @tarojs/taro declares export= types, but vite-plugin-taro target aliases expose runtime named exports.\nexport * from '@tarojs/taro'\nexport default Taro\n"],"mappings":";;;;AAGA,IAAI,MAAM,QAAQ,eAAe,GAC7B,MAAM,KAAK,iBAAiB,IAAI;AAKpC,IAAA,eAAe"}

package/dist/shim/h5.d.ts

@@ -0,0 +1,3 @@
+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/h5.js

@@ -0,0 +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 };

package/dist/shim/wx.d.ts

@@ -0,0 +1,3 @@
+export { createReactApp } from '@tarojs/plugin-framework-react/dist/runtime';
+export { default as ReactDOM } from '@tarojs/react';
+export { createPageConfig, createRecursiveComponentConfig } from '@tarojs/runtime';

package/dist/shim/wx.js

@@ -0,0 +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 };

package/dist/vite/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const isProd: boolean;
+export declare const nodeRequire: NodeJS.Require;

package/dist/vite/plugins.d.ts

@@ -0,0 +1,8 @@
+import { Plugin } from 'vite';
+import { TaroBuildContext } from './types.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 declare function createTaroConditionalDirectivePlugin(context: TaroBuildContext): Plugin;

package/dist/vite/tailwindcss.d.ts

@@ -0,0 +1,3 @@
+import { PluginOption } from 'vite';
+import { TaroBuildContext } from './types.js';
+export declare function createTailwindcssPlugins(context: TaroBuildContext): PluginOption[];

package/dist/vite/targets/h5.d.ts

@@ -0,0 +1,31 @@
+import { HtmlTagDescriptor, PluginOption, UserConfig } from 'vite';
+import { TaroBuildContext } from '../types.js';
+/**
+ * Checks whether an id belongs to an H5 virtual module.
+ */
+export declare function isH5VirtualModuleId(id: string): boolean;
+/**
+ * Loads generated source for H5 virtual modules.
+ */
+export declare function loadH5VirtualModule(cleanId: string, context: TaroBuildContext): string | undefined;
+/**
+ * Configures the Vite pieces needed for Taro H5 resolve/runtime behavior.
+ */
+export declare function createH5ViteConfig(): UserConfig;
+/**
+ * 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 declare function createH5SupportPlugins(): PluginOption[];
+/**
+ * Injects vite-plugin-taro's generated Web entry into Vite's HTML shell.
+ */
+export declare function createWebIndexHtmlTags(context: TaroBuildContext): HtmlTagDescriptor[] | undefined;
+/**
+ * Builds the generated Web entry around Taro's official Web router/runtime APIs.
+ * 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/h5.ts#L120-L150
+ */
+export declare function createWebEntry(context: TaroBuildContext): string;

package/dist/vite/targets/wx.d.ts

@@ -0,0 +1,74 @@
+import { UserConfig } from 'vite';
+import { TaroBuildContext, TaroPageOption } from '../types.js';
+/**
+ * Checks whether an id belongs to a wx virtual module.
+ */
+export declare function isWxVirtualModuleId(id: string): boolean;
+export declare function loadWxVirtualModule(cleanId: string, context: TaroBuildContext): string | undefined;
+/**
+ * Configures wx target entry, output, and chunk layout.
+ */
+export declare function createWxViteConfig(context: TaroBuildContext): UserConfig;
+type WechatAssetSource = string | Uint8Array;
+type WechatBundleModule = {
+    renderedExports?: string[];
+};
+type WechatBundleItem = {
+    type: 'asset' | 'chunk';
+    source?: WechatAssetSource;
+    modules?: Record<string, WechatBundleModule>;
+};
+type WechatBundle = Record<string, WechatBundleItem>;
+type WechatChunkEmitter = {
+    emitFile(chunk: {
+        type: 'chunk';
+        id: string;
+        fileName: string;
+        implicitlyLoadedAfterOneOf: string[];
+    }): string;
+};
+type WechatAssetEmitter = {
+    emitFile(asset: {
+        type: 'asset';
+        fileName: string;
+        source: WechatAssetSource;
+    }): string;
+};
+/**
+ * Emits page and component chunks like Taro Webpack's MiniPlugin generated entries.
+ *
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-webpack5-runner/src/plugins/MiniPlugin.ts#L228-L243
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-webpack5-runner/src/plugins/MiniPlugin.ts#L743-L777
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-webpack5-runner/src/plugins/TaroSingleEntryPlugin.ts#L18-L38
+ */
+export declare function emitWechatImplicitChunksForVirtualApp(emitter: WechatChunkEmitter, context: TaroBuildContext, cleanId: string): void;
+/**
+ * Builds the generated WeChat app entry that registers Taro's React App config.
+ * 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
+ */
+export declare function createWxAppEntry(context: TaroBuildContext): string;
+/**
+ * Builds a generated WeChat page entry that registers Taro's Page config.
+ *
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-loader/src/page.ts#L52-L78
+ */
+export declare function createWxPageEntry(pageOption: TaroPageOption): string;
+/**
+ * Builds the generated JS companion for comp.wxml/comp.json. Without it WeChat
+ * can load recursive markup, but it will not have Taro's properties or `eh` event
+ * dispatch method.
+ *
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-webpack5-runner/src/template/comp.ts#L1-L4
+ */
+export declare function createWxCompEntry(): string;
+/**
+ * Creates Taro-style Mini Program template/config/style companion files.
+ *
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-platform-weapp/src/program.ts#L33-L55
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-webpack5-runner/src/plugins/MiniPlugin.ts#L1198-L1311
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-webpack5-runner/src/plugins/MiniPlugin.ts#L1346-L1390
+ */
+export declare function emitWechatAssets(emitter: WechatAssetEmitter, bundle: WechatBundle, context: TaroBuildContext): void;
+export {};

package/dist/vite/taro.d.ts

@@ -0,0 +1,7 @@
+import { PluginOption } from 'vite';
+import { TaroPluginOptions } from './types.js';
+/**
+ * Creates the Vite/Rolldown plugin that emits either WeChat Mini Program files
+ * or a Taro Web app using the official Taro runtime packages.
+ */
+export default function taro(options: TaroPluginOptions): PluginOption[];

package/dist/vite/types.d.ts

@@ -0,0 +1,38 @@
+/** Plain JSON object emitted into Mini Program/Web config payloads. */
+export type JsonObject = Record<string, unknown>;
+/** Build target handled by this plugin. */
+export type TaroTarget = 'wx' | 'h5';
+/** Describes one React-backed page shared by WeChat Mini Program and Web builds. */
+export type TaroPageOption = {
+    /**
+     * Page route and output path, without file extension.
+     * Example: "pages/index/index" emits pages/index/index.{js,json,wxml,wxss}
+     * for WeChat and becomes the Web router path.
+     */
+    path: string;
+    /** Page JSON config merged into WeChat JSON and Web route config. */
+    config: JsonObject;
+};
+/** Required build inputs for the custom Vite/Rolldown Taro renderer plugin. */
+export interface TaroPluginOptions {
+    /** Active target for this Vite invocation. */
+    target: TaroTarget;
+    /** Source file that default-exports the root React app component. */
+    app: string;
+    /** Ordered page list; also becomes app.json.pages and Web route order. */
+    pages: TaroPageOption[];
+    /** Base app.json content. Its pages field is overwritten from options.pages. */
+    appJson: JsonObject;
+    /** project.config.json content emitted at the Mini Program root. */
+    projectConfigJson: JsonObject;
+    /** sitemap.json content emitted at the Mini Program root. */
+    sitemapJson: JsonObject;
+}
+export type TaroBuildContext = {
+    target: TaroTarget;
+    appComponentImport: string;
+    pages: TaroPageOption[];
+    appConfig: JsonObject;
+    projectConfigJson: JsonObject;
+    sitemapJson: JsonObject;
+};

package/dist/vite/utils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Derives a page component import from a Taro-style page path.
+ *
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-webpack5-runner/src/plugins/MiniPlugin.ts#L660-L668
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-webpack5-runner/src/utils/app.ts#L74-L90
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-loader/src/h5.ts#L12-L21
+ */
+export declare function createPageComponentImport(pagePath: string): string;
+/**
+ * Converts a local file path into an absolute ESM import path for Vite.
+ */
+export declare function toImportPath(filePath: string): string;
+/**
+ * Removes Rollup/Vite's internal virtual-module prefix before ID comparisons.
+ */
+export declare function stripVirtualPrefix(id: string): string;
+/**
+ * Uses Taro-style slash normalization, plus Vite query-string stripping for module IDs.
+ *
+ * https://github.com/NervJS/taro/blob/f0e5c39d5f04290db975670411e23c3a396e15f8/packages/taro-helper/src/utils.ts#L32-L34
+ */
+export declare function normalizeModuleId(id: string): string;

package/dist/vite.d.ts

@@ -0,0 +1,2 @@
+export { default } from './vite/taro.js';
+export type { TaroPageOption, TaroPluginOptions, TaroTarget } from './vite/types.js';