vite-plugin-taro 0.5.14 → 0.6.0

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

@@ -1,5 +1,5 @@
 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'
@@ -11,7 +11,7 @@ export function createJsonAssets({
     subpackages,
     nativeComponents
 }: {
-    options: VitePluginTaroOptions
+    options: VptOptions
     subpackages: readonly GeneratedSubpackage[]
     nativeComponents: readonly { name: string; componentPath: string }[]
 }): Rolldown.EmittedAsset[] {
@@ -29,15 +29,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 +60,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',

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

@@ -1,5 +1,5 @@
 import type { Plugin, PluginOption } from 'vite'
-import type { VitePluginTaroOptions } from '../../../options.ts'
+import type { VptOptions } from '../../../options.ts'
 import { esTarget } from '../../utils/constant.ts'
 import { packageRequire } from '../../utils/packages.ts'
 import { clientTaroNativeId } from '../client/constant.ts'
@@ -18,7 +18,7 @@ import { createWxStylePlugins } from './styles/plugins.ts'
 type WxResolver = ReturnType<typeof createResolver>
 
 /** Creates the complete plugin set for the wx target. */
-export function createWxTargetPlugins(options: VitePluginTaroOptions): PluginOption[] {
+export function createWxTargetPlugins(options: VptOptions): PluginOption[] {
     const resolver = createResolver(options)
 
     // Reuse the resolver instance's ordered application subset. Rolldown's complete input also contains bootstrap, transport,
@@ -31,7 +31,7 @@ export function createWxTargetPlugins(options: VitePluginTaroOptions): PluginOpt
 }
 
 /** Configures the complete wx target build pipeline. */
-function createWxPlugin(options: VitePluginTaroOptions, resolver: WxResolver): Plugin {
+function createWxPlugin(options: VptOptions, resolver: WxResolver): Plugin {
     const placer = createPlacer()
 
     return {

package/src/node/plugins/wx/render/transport.ts

@@ -4,7 +4,7 @@ import type { Rolldown } from 'vite'
 import { type AstTransformResult, replaceWithAst } from '../../../utils/transform.ts'
 import { getWxExecutionKind } from '../module.ts'
 
-const transportPlaceholder = '__VITE_PLUGIN_TARO_TRANSPORT__'
+const transportPlaceholder = '__VPT_TRANSPORT__'
 const moduleIdParameter = 'moduleId'
 const exportBindingParameter = 'exportBinding'
 

package/src/node/plugins/wx/resolve/resolver.ts

@@ -1,5 +1,5 @@
 import { normalizePath } from 'vite'
-import type { VitePluginTaroOptions, VitePluginTaroPageOption } from '../../../../options.ts'
+import type { VptOptions, VptPageOption } from '../../../../options.ts'
 import { normalizeModuleId, resolveAppComponentPath, resolvePageComponentPath } from '../../../utils/modules.ts'
 import { createAppConfig } from '../../../utils/project-config.ts'
 import { appComponentId } from '../../client/constant.ts'
@@ -25,7 +25,7 @@ import { specializePageCapsule } from './specialize-page-capsule.ts'
 type PrivateIdResolver = (importer: string | undefined, projectRoot: string) => string
 
 /** Creates the resolver and source specializer for the wx module graph. */
-export function createResolver(options: VitePluginTaroOptions) {
+export function createResolver(options: VptOptions) {
     const normalizedBootstrapPath = normalizePath(bootstrapPath)
     const normalizedPageCapsulePath = normalizePath(pageCapsulePath)
 
@@ -87,7 +87,7 @@ export function createResolver(options: VitePluginTaroOptions) {
 }
 
 /** Declares output entries and the ordered application subset that can own user styles. */
-function createEntryGraph(pages: readonly VitePluginTaroPageOption[]) {
+function createEntryGraph(pages: readonly VptPageOption[]) {
     const pageEntries = pages.map((page) => {
         return {
             capsuleId: createRouteModuleId({ moduleId: pageCapsulePath, pagePath: page.path }),
@@ -128,8 +128,8 @@ function requireConfiguredPage({
     pageByPath
 }: {
     moduleId: string | undefined
-    pageByPath: ReadonlyMap<string, VitePluginTaroPageOption>
-}): VitePluginTaroPageOption {
+    pageByPath: ReadonlyMap<string, VptPageOption>
+}): VptPageOption {
     const queryIndex = moduleId?.indexOf('?') ?? -1
     const pagePath = queryIndex === -1 ? undefined : new URLSearchParams(moduleId?.slice(queryIndex + 1)).get('route')
     const page = pagePath ? pageByPath.get(pagePath) : undefined

package/src/node/plugins/wx/resolve/specialize-bootstrap.ts

@@ -1,8 +1,8 @@
 import { types } from '@babel/core'
-import type { JsonObject } from '../../../../options.ts'
+import type { VptJsonObject } from '../../../../options.ts'
 import { type AstTransformResult, replaceWithAst } from '../../../utils/transform.ts'
 
-const appConfigPlaceholder = '__VITE_PLUGIN_TARO_APP_CONFIG__'
+const appConfigPlaceholder = '__VPT_APP_CONFIG__'
 
 /** Specializes the amphibious bootstrap with the shared App configuration. */
 export function specializeBootstrap({
@@ -13,7 +13,7 @@ export function specializeBootstrap({
 }: {
     code: string
     id: string
-    appConfig: JsonObject
+    appConfig: VptJsonObject
     sourcemap?: boolean
 }): Promise<AstTransformResult> {
     return replaceWithAst(

package/src/node/plugins/wx/resolve/specialize-page-capsule.ts

@@ -1,9 +1,9 @@
 import { types } from '@babel/core'
-import type { VitePluginTaroPageOption } from '../../../../options.ts'
+import type { VptPageOption } from '../../../../options.ts'
 import { type AstTransformResult, replaceWithAst } from '../../../utils/transform.ts'
 
-const pagePathPlaceholder = '__VITE_PLUGIN_TARO_PAGE_PATH__'
-const pageConfigPlaceholder = '__VITE_PLUGIN_TARO_PAGE_CONFIG__'
+const pagePathPlaceholder = '__VPT_PAGE_PATH__'
+const pageConfigPlaceholder = '__VPT_PAGE_CONFIG__'
 
 /** Specializes the Page capsule for one configured route. */
 export function specializePageCapsule({
@@ -14,7 +14,7 @@ export function specializePageCapsule({
 }: {
     code: string
     id: string
-    page: VitePluginTaroPageOption
+    page: VptPageOption
     sourcemap?: boolean
 }): Promise<AstTransformResult> {
     return replaceWithAst(

package/src/node/utils/project-config.ts

@@ -1,7 +1,7 @@
-import type { JsonObject, VitePluginTaroOptions } from '../../options.ts'
+import type { VptJsonObject, VptOptions } from '../../options.ts'
 
 /** Creates shared App configuration with configured Page order as the authoritative value. */
-export function createAppConfig(options: VitePluginTaroOptions): JsonObject {
+export function createAppConfig(options: VptOptions): VptJsonObject {
     const { subPackages: _subPackages, subpackages: _subpackages, ...appJson } = options.appJson
     return {
         ...appJson,

package/src/node/{vite-plugin.ts → vpt.ts}

@@ -1,13 +1,13 @@
 import react from '@vitejs/plugin-react'
 import type { PluginOption } from 'vite'
-import type { VitePluginTaroOptions } from '../options.ts'
+import type { VptOptions } from '../options.ts'
 import { createClientTaroPlugin } from './plugins/client/client-taro.ts'
 import { createConditionalDirectivePlugin } from './plugins/conditional/conditional-directives.ts'
 import { createH5TargetPlugins } from './plugins/h5/plugins.ts'
 import { createWxTargetPlugins } from './plugins/wx/plugins.ts'
 
 /** Creates the Vite plugins for one Taro target. */
-export default function vitePluginTaro(options: VitePluginTaroOptions): PluginOption[] {
+export default function vpt(options: VptOptions): PluginOption[] {
     return [
         createConditionalDirectivePlugin(options.target),
         createClientTaroPlugin(options.target),

package/src/options.ts

@@ -1,24 +1,82 @@
 /** A JSON object used by generated target configs. */
-export type JsonObject = Record<string, unknown>
+export type VptJsonObject = Record<string, unknown>
 
 /** Build target handled by this plugin. */
-export type VitePluginTaroTarget = 'wx' | 'h5'
+export type VptTarget = 'wx' | 'h5'
 
 /** Configures one Taro page. */
-export type VitePluginTaroPageOption = {
-    /** Taro route and output path without a file extension. */
+export type VptPageOption = {
+    /**
+     * Taro route and output path without a file extension.
+     *
+     * The plugin resolves the page component from `src/${path}.tsx`, relative to the Vite project root. For example,
+     * `pages/home/index` resolves to `src/pages/home/index.tsx` and is emitted under `pages/home/index` for `wx`.
+     */
     path: string
 
-    config: JsonObject
+    /**
+     * Target-independent Taro page configuration.
+     *
+     * For `wx`, these values form the generated `<path>.json`; the plugin augments `usingComponents` with its generated
+     * component registrations. For `h5`, the values are added to the corresponding Taro router entry.
+     */
+    config: VptJsonObject
 }
 
-/** Configures the Vite Taro plugin. */
-export interface VitePluginTaroOptions {
-    target: VitePluginTaroTarget
+/** Configures vpt for one build target. */
+export interface VptOptions {
+    /**
+     * Platform produced by the current Vite invocation.
+     *
+     * Use `wx` to emit a WeChat Mini Program or `h5` to emit a browser application. The selected target controls Taro
+     * module resolution, conditional compilation, runtime bootstrapping, style processing, and output generation.
+     */
+    target: VptTarget
+
+    /**
+     * Source module that default-exports the root React application component.
+     *
+     * Relative paths are resolved from Vite's project root, for example `src/app.tsx`. The component wraps the active
+     * page through its `children` prop and is the appropriate place to import application-wide styles.
+     */
     app: string
-    pages: VitePluginTaroPageOption[]
-    appJson: JsonObject
-    projectConfigJson: JsonObject
-    projectPrivateConfigJson?: JsonObject
-    sitemapJson: JsonObject
+
+    /**
+     * Complete ordered list of application pages.
+     *
+     * The declared order becomes the `pages` order in the generated `app.json`, the H5 route order, and the Page order
+     * in the application style cascade. Each Page source is resolved according to its `path`.
+     */
+    pages: VptPageOption[]
+
+    /**
+     * Target-independent Taro application configuration.
+     *
+     * For `wx`, these values form the generated `app.json`. For `h5`, they configure the Taro application and router.
+     * The plugin always derives `pages` from {@link pages}; caller-provided `pages`, `subPackages`, and `subpackages`
+     * values are discarded because the build pipeline owns page order and generated package placement.
+     */
+    appJson: VptJsonObject
+
+    /**
+     * WeChat DevTools project configuration written to `project.config.json` without merging.
+     *
+     * This option is required so one configuration shape can be shared between targets, but it is only emitted for a
+     * `wx` build and is ignored for `h5`.
+     */
+    projectConfigJson: VptJsonObject
+
+    /**
+     * Local WeChat DevTools overrides written to `project.private.config.json` without merging.
+     *
+     * The file is emitted only when this value is provided for a `wx` build. It is ignored for `h5`.
+     */
+    projectPrivateConfigJson?: VptJsonObject
+
+    /**
+     * WeChat Mini Program indexing rules written to `sitemap.json` without merging.
+     *
+     * The file is emitted only when this value is provided for a `wx` build. It is ignored for `h5`.
+     */
+    sitemapJson?: VptJsonObject
 }

package/src/runtime/h5/app.ts

@@ -8,16 +8,16 @@ import ReactDOM from 'react-dom/client'
 // @ts-expect-error: The H5 build resolves this private App component.
 import AppComponent from '\0vpt:app-component'
 
-declare const __VITE_PLUGIN_TARO_H5_APP_CONFIG__: SpaRouterConfig
-declare const __VITE_PLUGIN_TARO_H5_ROUTES__: Route[]
+declare const __VPT_H5_APP_CONFIG__: SpaRouterConfig
+declare const __VPT_H5_ROUTES__: Route[]
 
 const browserWindow = window as unknown as Window &
     typeof window & {
         __taroAppConfig: SpaRouterConfig
     }
-const config = __VITE_PLUGIN_TARO_H5_APP_CONFIG__
+const config = __VPT_H5_APP_CONFIG__
 browserWindow.__taroAppConfig = config
-config.routes = __VITE_PLUGIN_TARO_H5_ROUTES__
+config.routes = __VPT_H5_ROUTES__
 const app = createReactApp(AppComponent, React, ReactDOM, config)
 const history = createHashHistory({ window: browserWindow })
 handleAppMount(config, history)

package/src/runtime/wx/amphibious/bootstrap.ts

@@ -2,10 +2,10 @@
 import '../systemjs/system-core.js'
 import { transport } from './transport.ts'
 
-declare const __VITE_PLUGIN_TARO_APP_CONFIG__: Record<string, unknown>
+declare const __VPT_APP_CONFIG__: Record<string, unknown>
 
 /** Shares one App configuration object between the specialized bootstrap and App capsule. */
-export const appConfig = __VITE_PLUGIN_TARO_APP_CONFIG__
+export const appConfig = __VPT_APP_CONFIG__
 
 // WX has no modulepreload transport. Genuine application import() boundaries retain System.import() and may load
 // asynchronous subpackage or top-level-await graphs through this identity wrapper.

package/src/runtime/wx/amphibious/transport.ts

@@ -2,9 +2,7 @@
 // amphibious boundary that publishes native namespaces to SystemJS without re-evaluating their module bodies.
 
 /** Materialized from the preliminary output graph before Rolldown finalizes content hashes. */
-declare const __VITE_PLUGIN_TARO_TRANSPORT__: (
-    moduleId: string
-) => System.Registration | PromiseLike<System.Registration>
+declare const __VPT_TRANSPORT__: (moduleId: string) => System.Registration | PromiseLike<System.Registration>
 
 /** 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/src/runtime/wx/capsule/page.ts

@@ -5,14 +5,9 @@ import './app.ts'
 import PageComponent from '\0vpt:page-component'
 import { createPageConfig } from './taro-runtime.ts'
 
-declare const __VITE_PLUGIN_TARO_PAGE_PATH__: string
-declare const __VITE_PLUGIN_TARO_PAGE_CONFIG__: Record<string, unknown>
+declare const __VPT_PAGE_PATH__: string
+declare const __VPT_PAGE_CONFIG__: Record<string, unknown>
 
-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/src/vite.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/node/vite-plugin.d.ts

@@ -1,4 +0,0 @@
-import type { PluginOption } from 'vite';
-import type { VitePluginTaroOptions } from '../options.ts';
-/** Creates the Vite plugins for one Taro target. */
-export default function vitePluginTaro(options: VitePluginTaroOptions): PluginOption[];