vite-plugin-taro 0.5.16 → 0.6.1

package/dist/runtime/wx/amphibious/transport.js

@@ -1,4 +1,4 @@
 // Transport itself executes only as native CommonJS. It lives beside bootstrap because together they implement the
 // amphibious boundary that publishes native namespaces to SystemJS without re-evaluating their module bodies.
 /** Dispatches to one generated literal require and bridges amphibious CommonJS namespaces inline. */
-export const transport = __VITE_PLUGIN_TARO_TRANSPORT__;
+export const transport = __VPT_TRANSPORT__;

package/dist/runtime/wx/capsule/page.js

@@ -3,5 +3,5 @@ import './app.js';
 // @ts-expect-error: The wx build replaces this private import with the configured Page component.
 import PageComponent from '\0vpt:page-component';
 import { createPageConfig } from './taro-runtime.js';
-const config = createPageConfig(PageComponent, __VITE_PLUGIN_TARO_PAGE_PATH__, { root: { cn: [] } }, __VITE_PLUGIN_TARO_PAGE_CONFIG__);
+const config = createPageConfig(PageComponent, __VPT_PAGE_PATH__, { root: { cn: [] } }, __VPT_PAGE_CONFIG__);
 export default config;

package/dist/vite.d.ts

@@ -1,2 +1,2 @@
-export { default } from './node/vite-plugin.ts';
-export type { VitePluginTaroOptions, VitePluginTaroPageOption, VitePluginTaroTarget } from './options.ts';
+export { default } from './node/vpt.ts';
+export type { VptJsonObject, VptOptions, VptPageOption, VptTarget } from './options.ts';

package/dist/vite.js

@@ -1 +1 @@
-export { default } from './node/vite-plugin.js';
+export { default } from './node/vpt.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-taro",
-  "version": "0.5.16",
+  "version": "0.6.1",
   "author": "sep2",
   "description": "Vite 8 plugin for building one React/Taro codebase for WeChat Mini Program and H5 targets.",
   "type": "module",
@@ -76,8 +76,8 @@
     "rxjs": "^7.8.2",
     "tailwindcss": "^4.3.3",
     "weapp-tailwindcss": "^5.2.11",
-    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.5.16",
-    "@tarojs/react": "npm:vite-plugin-taro-react@0.5.16"
+    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.6.1",
+    "@tarojs/react": "npm:vite-plugin-taro-react@0.6.1"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/node/plugins/client/client-taro.ts

@@ -1,5 +1,5 @@
 import { normalizePath, type Plugin } from 'vite'
-import type { VitePluginTaroTarget } from '../../../options.ts'
+import type { VptTarget } from '../../../options.ts'
 import { normalizeModuleId } from '../../utils/modules.ts'
 import { resolvePackageFile } from '../../utils/packages.ts'
 import { clientTaroNativeId } from './constant.ts'
@@ -32,7 +32,7 @@ const clientTaroModules = new Map([
 ])
 
 /** Creates the shared Taro facade backed by the selected target's API implementation. */
-export function createClientTaroPlugin(target: VitePluginTaroTarget): Plugin {
+export function createClientTaroPlugin(target: VptTarget): Plugin {
     const platformTaroId = resolvePlatformTaroId(target)
 
     return {
@@ -62,7 +62,7 @@ export function createClientTaroPlugin(target: VitePluginTaroTarget): Plugin {
     }
 }
 
-function resolvePlatformTaroId(target: VitePluginTaroTarget): string {
+function resolvePlatformTaroId(target: VptTarget): string {
     return target === 'h5' ? '@tarojs/plugin-platform-h5/dist/runtime/apis' : '@tarojs/taro'
 }
 

package/src/node/plugins/conditional/conditional-directives.ts

@@ -1,9 +1,9 @@
 import type { Plugin } from 'vite'
-import type { VitePluginTaroTarget } from '../../../options.ts'
+import type { VptTarget } from '../../../options.ts'
 import { normalizeModuleId } from '../../utils/modules.ts'
 
 /** Creates source-level target conditional handling shared by H5 and WX. */
-export function createConditionalDirectivePlugin(target: VitePluginTaroTarget): Plugin {
+export function createConditionalDirectivePlugin(target: VptTarget): Plugin {
     return {
         name: 'vpt:conditional-directives',
         enforce: 'pre',
@@ -37,7 +37,7 @@ type DirectiveFrame = {
 }
 
 /** Keeps only the source branches active for one build target. */
-function transformConditionalDirectives(code: string, target: VitePluginTaroTarget): string {
+function transformConditionalDirectives(code: string, target: VptTarget): string {
     const lines = code.match(/[^\n]*(?:\n|$)/g) ?? []
     const frames: DirectiveFrame[] = []
     let transformed = ''

package/src/node/plugins/h5/plugins.ts

@@ -1,7 +1,7 @@
 import babel, { defineRolldownBabelPreset } from '@rolldown/plugin-babel'
 import type { HtmlTagDescriptor, Plugin, PluginOption } from 'vite'
 import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
-import type { VitePluginTaroOptions } from '../../../options.ts'
+import type { VptOptions } from '../../../options.ts'
 import { esTarget } from '../../utils/constant.ts'
 import { toViteFileImportPath } from '../../utils/modules.ts'
 import { packageRequire } from '../../utils/packages.ts'
@@ -12,7 +12,7 @@ import { createStencilClientAdapter } from './create-stencil-client-adapter.ts'
 import { createModuleResolver } from './resolver/module-resolver.ts'
 
 /** Creates the plugins that own the H5 target. */
-export function createH5TargetPlugins(options: VitePluginTaroOptions): PluginOption[] {
+export function createH5TargetPlugins(options: VptOptions): PluginOption[] {
     return [
         WeappTailwindcss({
             appType: 'weapp-vite',
@@ -36,7 +36,7 @@ export function createH5TargetPlugins(options: VitePluginTaroOptions): PluginOpt
 }
 
 /** Configures H5 resolution and supplies the specialized physical application entry. */
-function createH5TargetPlugin(options: VitePluginTaroOptions): Plugin {
+function createH5TargetPlugin(options: VptOptions): Plugin {
     const moduleResolver = createModuleResolver(options)
 
     return {

package/src/node/plugins/h5/resolver/module-resolver.ts

@@ -1,12 +1,12 @@
 import { normalizePath } from 'vite'
-import type { VitePluginTaroOptions } from '../../../../options.ts'
+import type { VptOptions } from '../../../../options.ts'
 import { normalizeModuleId, resolveAppComponentPath } from '../../../utils/modules.ts'
 import { appComponentId } from '../../client/constant.ts'
 import { h5AppPath } from '../constant.ts'
 import { transformH5App } from '../transform-app.ts'
 
 /** Creates H5 application module resolution and specialization. */
-export function createModuleResolver(options: VitePluginTaroOptions) {
+export function createModuleResolver(options: VptOptions) {
     return {
         resolveId({ id, projectRoot }: { id: string; projectRoot: string }): string | undefined {
             if (id === appComponentId) {

package/src/node/plugins/h5/transform-app.ts

@@ -1,11 +1,11 @@
 import { types } from '@babel/core'
-import type { VitePluginTaroOptions, VitePluginTaroPageOption } from '../../../options.ts'
+import type { VptOptions, VptPageOption } from '../../../options.ts'
 import { createPageComponentImportPath } from '../../utils/modules.ts'
 import { createAppConfig } from '../../utils/project-config.ts'
 import { type AstTransformResult, replaceWithAst } from '../../utils/transform.ts'
 
-const appConfigPlaceholder = '__VITE_PLUGIN_TARO_H5_APP_CONFIG__'
-const routesPlaceholder = '__VITE_PLUGIN_TARO_H5_ROUTES__'
+const appConfigPlaceholder = '__VPT_H5_APP_CONFIG__'
+const routesPlaceholder = '__VPT_H5_ROUTES__'
 
 /** Specializes the physical H5 App for one configured project. */
 export async function transformH5App({
@@ -17,7 +17,7 @@ export async function transformH5App({
 }: {
     code: string
     id: string
-    options: VitePluginTaroOptions
+    options: VptOptions
     projectRoot: string
     sourcemap?: boolean
 }): Promise<AstTransformResult> {
@@ -56,7 +56,7 @@ function createRoute({
     page,
     projectRoot
 }: {
-    page: VitePluginTaroPageOption
+    page: VptPageOption
     projectRoot: string
 }): ReturnType<typeof types.objectExpression> {
     const pageComponentPath = createPageComponentImportPath({ pagePath: page.path, projectRoot })

package/src/node/plugins/wx/chunk-path.ts

@@ -0,0 +1,22 @@
+import path from 'node:path'
+
+/** Physical directory in which Rolldown writes generated JavaScript chunks inside each native package. */
+export const generatedChunkDirectory = 'assets'
+
+/** Projects one Rolldown-owned physical candidate path into the package-neutral SystemJS identity. */
+export function toLogicalChunkId(physicalChunkId: string): string {
+    return path.posix.relative(generatedChunkDirectory, physicalChunkId)
+}
+
+/** Resolves one relative Rolldown-generated import to its preliminary physical chunk path. */
+export function resolvePhysicalChunkReference(importerChunkId: string, reference: string): string {
+    if (!reference.startsWith('./') && !reference.startsWith('../')) {
+        throw new Error(`Expected a relative chunk reference in ${importerChunkId}: ${reference}`)
+    }
+    return path.posix.join(path.posix.dirname(importerChunkId), reference)
+}
+
+/** Projects one relative Rolldown-generated import into its package-neutral SystemJS identity. */
+export function resolveLogicalChunkReference(importerChunkId: string, reference: string): string {
+    return toLogicalChunkId(resolvePhysicalChunkReference(importerChunkId, reference))
+}

package/src/node/plugins/wx/dev/dev-host.ts

@@ -5,7 +5,7 @@ import colors from 'picocolors'
 import { type DevEngine, type DevOptions, dev } from 'rolldown/experimental'
 import { asyncScheduler } from 'rxjs'
 import type { Connect, ViteDevServer } from 'vite'
-import type { VitePluginTaroOptions } from '../../../../options.ts'
+import type { VptOptions } from '../../../../options.ts'
 import { createHmrResultsStream } from './create-hmr-results-stream.ts'
 import { createStyleCapture, type StyleCaptureAction } from './create-style-capture.ts'
 import {
@@ -61,7 +61,7 @@ export async function createWxDevHost({
     applicationEntryIds
 }: {
     server: ViteDevServer
-    options: VitePluginTaroOptions
+    options: VptOptions
     applicationEntryIds: readonly string[]
 }): Promise<WxDevHost> {
     const bundledDev = getBundledDev(server)

package/src/node/plugins/wx/dev/plugins.ts

@@ -1,5 +1,5 @@
 import { normalizePath, type PluginOption, transformWithOxc } from 'vite'
-import type { VitePluginTaroOptions } from '../../../../options.ts'
+import type { VptOptions } from '../../../../options.ts'
 import { esTarget } from '../../../utils/constant.ts'
 import { memoize } from '../../../utils/memoize.ts'
 import { normalizeModuleId } from '../../../utils/modules.ts'
@@ -22,10 +22,7 @@ export function isWxClientEnvironment(environment: Readonly<{ name: string }>):
  * The ordered application entries cross this configuration boundary unchanged so the host can compose global CSS without
  * reconstructing the resolver's App/Page ownership policy from unrelated Rolldown shell and transport entries.
  */
-export function createWxDevelopmentPlugin(
-    options: VitePluginTaroOptions,
-    applicationEntryIds: readonly string[]
-): PluginOption[] {
+export function createWxDevelopmentPlugin(options: VptOptions, applicationEntryIds: readonly string[]): PluginOption[] {
     /*
      * Vite creates this plugin descriptor before a server or DevEngine exists, then invokes configureServer and closeBundle on
      * different lifecycle stacks. This mutable handle transfers the one client-owned host between those hooks: configureServer

package/src/node/plugins/wx/dev/wx-dev-options.ts

@@ -3,7 +3,7 @@ import type { InputOptions, OutputOptions, Plugin } from 'rolldown'
 import { build } from 'rolldown'
 import { type DevEngine, viteReporterPlugin } from 'rolldown/experimental'
 import type { ViteDevServer } from 'vite'
-import type { VitePluginTaroOptions } from '../../../../options.ts'
+import type { VptOptions } from '../../../../options.ts'
 import { once } from '../../../utils/once.ts'
 import { resolvePackageFile } from '../../../utils/packages.ts'
 import { appShellFileName } from '../module.ts'
@@ -35,7 +35,7 @@ export function installWxDevOptions({
 }: {
     bundledDev: BundledDev
     server: ViteDevServer
-    options: VitePluginTaroOptions
+    options: VptOptions
     hostPlugins: Plugin[]
 }): void {
     /*
@@ -68,12 +68,26 @@ export function installWxDevOptions({
          * mutating configuredOutput itself would leak development normalization back into the user's resolved Vite config.
          */
         Object.assign(output, configured, {
+            // Development output is overwritten in place after every complete build. Strip hash placeholders from the
+            // configured asset pattern so old files cannot accumulate and native JSON/WXML references remain stable.
             assetFileNames: createStableFileNames(configured.assetFileNames, 'assets/[name][extname]'),
+            // Banners create physical CommonJS edges after graph analysis: App initializes the dev runtime and each Page
+            // consumes the stable patch journal without allowing those host-only files into the application chunk graph.
             banner: createEntryBanner(pageFiles),
+            // Preserve the configured directory/name shape while removing content hashes. Stable chunk paths let DevTools
+            // overwrite executable files and let cumulative HMR patches address one persistent physical module identity.
             chunkFileNames: createStableFileNames(configured.chunkFileNames, 'assets/[name].js'),
+            // Native entry paths are public Mini Program routes (`app.js`, `pages/.../index.js`); development must never hash
+            // or relocate them because DevTools determines App/Page reload behavior from those exact filenames.
             entryFileNames: createStableFileNames(configured.entryFileNames, '[name]'),
+            // Keep ESM until the existing WX renderChunk pipeline classifies each final chunk and converts capsules to
+            // System.register data or native/amphibious entries to CommonJS. Choosing CommonJS here would erase that boundary.
             format: 'es',
+            // Bundled development emits complete physical output repeatedly. Minifying bounds disk transfer and DevTools
+            // compile work; source-level HMR diagnostics still come from Vite/Rolldown before this final output pass.
             minify: true,
+            // DevTools executes physical WX files and HMR applies module factories rather than browser source maps. Disabling
+            // maps avoids extra output files and prevents Vite's Oxc sourcemap transform from touching generated host code.
             sourcemap: false
         })
 
@@ -84,9 +98,16 @@ export function installWxDevOptions({
         rolldownOptions.experimental ??= {}
         const existingDevMode = rolldownOptions.experimental.devMode
         rolldownOptions.experimental.devMode = {
+            // Retain unknown user/forward-compatible devMode fields while the three explicit WX invariants below win.
             ...(typeof existingDevMode === 'object' ? existingDevMode : {}),
+            // Install the WX-adapted self-contained Rolldown runtime. It consumes physical patch journals and reports
+            // acknowledgements/rebuild requests through the host bridge instead of relying on browser globals or sockets.
             implement: await bundleRuntimeSource(),
+            // Produce a complete output graph on the initial build. Lazy per-request compilation cannot establish the closed
+            // App/Page graph, native companions, style sidecars, and build identity required before any patch is admitted.
             lazy: false,
+            // Keep Rolldown's common runtime injection because generated application factories call its module registry and
+            // HMR primitives. Skipping it would leave the custom implementation without the runtime surface it extends.
             skipCommonRuntimeInjection: false
         }
 

package/src/node/plugins/wx/native/create-native-component-output.ts

@@ -1,16 +1,18 @@
 import { readFile } from 'node:fs/promises'
 import path from 'node:path'
 import type { Rolldown } from 'vite'
-import { isGeneratedSubpackageFile } from '../placement/plan.ts'
+import type { PackageLocation } from '../placer/placement.ts'
 import { getNativeComponentSources } from './native-component-assets.ts'
 
 /** Creates opaque native files and their registrations from each surviving JSX interface module. */
 export async function createNativeComponentOutput({
     bundle,
-    getModuleInfo
+    getModuleInfo,
+    getPackageLocation
 }: {
     bundle: Rolldown.OutputBundle
     getModuleInfo: (moduleId: string) => { meta: Rolldown.CustomPluginOptions } | null
+    getPackageLocation(chunk: Rolldown.OutputChunk): PackageLocation
 }) {
     // Files and registrations accumulate in final chunk order for deterministic output.
     const files: Rolldown.EmittedAsset[] = []
@@ -25,9 +27,8 @@ export async function createNativeComponentOutput({
         if (output.type !== 'chunk') {
             continue
         }
-        const packageRoot = isGeneratedSubpackageFile(output.fileName)
-            ? path.posix.dirname(path.posix.dirname(output.fileName))
-            : undefined
+        const location = getPackageLocation(output)
+        const packageRoot = location.kind === 'subpackage' ? location.root : undefined
 
         for (const moduleId of output.moduleIds) {
             const sources = getNativeComponentSources(getModuleInfo(moduleId)?.meta)

package/src/node/plugins/wx/output/files.ts

@@ -1,7 +1,7 @@
 import type { Rolldown } from 'vite'
-import type { VitePluginTaroOptions } from '../../../../options.ts'
+import type { VptOptions } from '../../../../options.ts'
 import { createNativeComponentOutput } from '../native/create-native-component-output.ts'
-import type { GeneratedSubpackage } from '../placement/placer.ts'
+import type { GeneratedSubpackage, PackageLocation } from '../placer/placement.ts'
 import { createJsonAssets } from './json.ts'
 import { createTemplateAssets } from './templates.ts'
 
@@ -10,14 +10,16 @@ export async function createOutputFiles({
     bundle,
     options,
     subpackages,
-    getModuleInfo
+    getModuleInfo,
+    getPackageLocation
 }: {
     bundle: Rolldown.OutputBundle
-    options: VitePluginTaroOptions
+    options: VptOptions
     subpackages: readonly GeneratedSubpackage[]
     getModuleInfo: (moduleId: string) => { meta: Rolldown.CustomPluginOptions } | null
+    getPackageLocation(chunk: Rolldown.OutputChunk): PackageLocation
 }): Promise<Rolldown.EmittedFile[]> {
-    const nativeOutput = await createNativeComponentOutput({ bundle, getModuleInfo })
+    const nativeOutput = await createNativeComponentOutput({ bundle, getModuleInfo, getPackageLocation })
 
     return [
         {

package/src/node/plugins/wx/output/json.ts

@@ -1,8 +1,7 @@
 import type { Rolldown } from 'vite'
-import type { JsonObject, VitePluginTaroOptions, VitePluginTaroPageOption } from '../../../../options.ts'
+import type { VptJsonObject, VptOptions, VptPageOption } from '../../../../options.ts'
 import { createAppConfig } from '../../../utils/project-config.ts'
-import type { GeneratedSubpackage } from '../placement/placer.ts'
-import { isGeneratedSubpackageFile } from '../placement/plan.ts'
+import { type GeneratedSubpackage, isGeneratedSubpackageFile } from '../placer/placement.ts'
 import { toRootRelativePath } from './relative-root.ts'
 
 /** Creates every configured native JSON asset. */
@@ -11,7 +10,7 @@ export function createJsonAssets({
     subpackages,
     nativeComponents
 }: {
-    options: VitePluginTaroOptions
+    options: VptOptions
     subpackages: readonly GeneratedSubpackage[]
     nativeComponents: readonly { name: string; componentPath: string }[]
 }): Rolldown.EmittedAsset[] {
@@ -29,15 +28,15 @@ export function createJsonAssets({
             ? [createJsonAsset('project.private.config.json', options.projectPrivateConfigJson)]
             : []),
 
-        createJsonAsset('sitemap.json', options.sitemapJson)
+        ...(options.sitemapJson ? [createJsonAsset('sitemap.json', options.sitemapJson)] : [])
     ]
 }
 
 /** Creates Page JSON with generated Taro and native component registrations. */
 function createPageJson(
-    page: VitePluginTaroPageOption,
+    page: VptPageOption,
     nativeComponents: readonly { name: string; componentPath: string }[]
-): JsonObject {
+): VptJsonObject {
     const usingComponents = isJsonObject(page.config.usingComponents) ? page.config.usingComponents : {}
 
     // Cross-package components require a placeholder while WeChat downloads their generated subpackage. Paths are
@@ -60,17 +59,17 @@ function createPageJson(
 }
 
 /** Tests whether a configured JSON value can be merged as an object. */
-function isJsonObject(value: unknown): value is JsonObject {
+function isJsonObject(value: unknown): value is VptJsonObject {
     return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
 /** Serializes one native JSON object with stable formatting. */
-export function renderJson(value: JsonObject): string {
+export function renderJson(value: VptJsonObject): string {
     return `${JSON.stringify(value, null, 4)}\n`
 }
 
 /** Creates one native JSON asset. */
-function createJsonAsset(fileName: string, value: JsonObject): Rolldown.EmittedAsset {
+function createJsonAsset(fileName: string, value: VptJsonObject): Rolldown.EmittedAsset {
     return {
         type: 'asset',
         fileName,

package/src/node/plugins/wx/output/templates.ts

@@ -1,7 +1,7 @@
 import { recursiveMerge } from '@tarojs/helper'
 import { Weapp as WxPlatform } from '@tarojs/plugin-platform-weapp'
 import type { Rolldown } from 'vite'
-import type { JsonObject, VitePluginTaroOptions } from '../../../../options.ts'
+import type { VptJsonObject, VptOptions } from '../../../../options.ts'
 import { normalizeModuleId } from '../../../utils/modules.ts'
 import { packageRequire } from '../../../utils/packages.ts'
 import { renderJson } from './json.ts'
@@ -19,7 +19,7 @@ const taroComponentsModulePath = packageRequire.resolve('@tarojs/plugin-platform
 /** Creates Taro's shared WeChat templates and native WXML/WXSS companions for every Page. */
 export function createTemplateAssets(
     bundle: Rolldown.OutputBundle,
-    options: VitePluginTaroOptions,
+    options: VptOptions,
     nativeComponents: readonly {
         name: string
         fields: readonly string[]
@@ -121,7 +121,7 @@ function toDashed(value: string): string {
 }
 
 /** Creates the recursive component configuration expected by Taro's templates. */
-function createComponentJson(): JsonObject {
+function createComponentJson(): VptJsonObject {
     return {
         component: true,
         styleIsolation: 'apply-shared',