vite-plugin-taro 0.3.2 → 0.4.1

package/src/node/utils/modules.ts

@@ -1,46 +1,44 @@
-/** Node-side helpers for application module files, Vite import specifiers, and normalized module IDs. */
 import path from 'node:path'
 
-/**
- * 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 function createPageComponentImportPath(pagePath: string): string {
-    return toViteFileImportPath(createPageComponentFile(pagePath))
-}
-
-/**
- * Resolves the source file backing a Taro-style page path.
- */
-function createPageComponentFile(pagePath: string): string {
-    return path.resolve(`src/${pagePath}.tsx`)
-}
-
-/**
- * Converts a local file path into a Vite file-system import specifier.
- *
- * Rolldown does not reliably resolve raw Windows absolute paths from virtual
- * module source, so generated imports use Vite's /@fs/ prefix instead.
- */
-export function toViteFileImportPath(filePath: string): string {
-    return `/@fs/${normalizeModuleId(path.resolve(filePath))}`
+type AppComponentPathOptions = {
+    appPath: string
+    projectRoot: string
+}
+
+type PageComponentPathOptions = {
+    pagePath: string
+    projectRoot: string
+}
+
+/** Resolves a final relative reference to the canonical output chunk ID used by the WX module registry. */
+export function resolveChunkReference(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)
+}
+
+/** Resolves the source file for the configured App component. */
+export function resolveAppComponentPath({ appPath, projectRoot }: AppComponentPathOptions): string {
+    return path.resolve(projectRoot, appPath)
+}
+
+/** Resolves the source file for one configured Page component. */
+export function resolvePageComponentPath({ pagePath, projectRoot }: PageComponentPathOptions): string {
+    return path.resolve(projectRoot, 'src', `${pagePath}.tsx`)
 }
 
-/**
- * Removes Rollup/Vite's internal virtual-module prefix before ID comparisons.
- */
-export function stripVirtualPrefix(id: string): string {
-    return id.startsWith('\0') ? id.slice(1) : id
+/** Creates a portable import for one configured Page component. */
+export function createPageComponentImportPath(options: PageComponentPathOptions): string {
+    return toViteFileImportPath(resolvePageComponentPath(options))
 }
 
-/**
- * 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
- */
+/** Normalizes a file-backed Vite module ID for stable comparisons. */
 export function normalizeModuleId(id: string): string {
-    return id.replace(/\\/g, '/').replace(/\?.*$/, '')
+    return id.replaceAll('\\', '/').replace(/\?.*$/, '')
+}
+
+/** Converts a local file path into Vite's portable file-system import form. */
+export function toViteFileImportPath(filePath: string): string {
+    return `/@fs/${normalizeModuleId(path.resolve(filePath))}`
 }

package/src/node/utils/once.ts

@@ -0,0 +1,21 @@
+/**
+ * Creates a function that runs its argument once and returns the first result on every
+ * later call.
+ *
+ * @example
+ * const initialize = once(createApplication)
+ * initialize() // runs createApplication
+ * initialize() // returns the cached result
+ */
+export function once<F extends (...args: never[]) => unknown>(func: F): F {
+    let called = false
+    let cache: ReturnType<F>
+
+    return ((...args: Parameters<F>): ReturnType<F> => {
+        if (!called) {
+            called = true
+            cache = func(...args) as ReturnType<F>
+        }
+        return cache
+    }) as F
+}

package/src/node/utils/packages.ts

@@ -1,10 +1,11 @@
-/** Resolves dependencies and package-owned files relative to the installed plugin rather than the user project. */
 import { createRequire } from 'node:module'
 import path from 'node:path'
+import { normalizeModuleId } from './modules.ts'
 
 export const packageRequire = createRequire(import.meta.url)
 const packageRoot = path.dirname(packageRequire.resolve('vite-plugin-taro/package.json'))
 
+/** Resolves a file shipped by this package as a portable Vite module ID. */
 export function resolvePackageFile(...segments: string[]): string {
-    return path.join(packageRoot, ...segments)
+    return normalizeModuleId(path.join(packageRoot, ...segments))
 }

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

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

package/src/node/utils/serialized-task-queue.ts

@@ -0,0 +1,20 @@
+/** Runs recoverable background tasks in insertion order and reports failures without blocking later work. */
+export class SerializedTaskQueue {
+    private tail: Promise<void> = Promise.resolve()
+    private readonly reportError: (operation: string, error: unknown) => void
+
+    constructor(reportError: (operation: string, error: unknown) => void) {
+        this.reportError = reportError
+    }
+
+    enqueue(operation: string, task: () => Promise<void>): void {
+        this.tail = this.tail.then(task).catch((error) => {
+            this.reportError(operation, error)
+        })
+    }
+
+    /** Waits for every task that was queued when this method was called. */
+    async waitForIdle(): Promise<void> {
+        await this.tail
+    }
+}

package/src/node/utils/transform.ts

@@ -0,0 +1,82 @@
+import { type PluginItem, transformSync } from '@babel/core'
+import generate from '@babel/generator'
+import { type Rolldown, transformWithOxc } from 'vite'
+import { esTarget } from './constant.ts'
+
+export type AstTransformResult = {
+    code: string
+    map: Rolldown.ExistingRawSourceMap | null
+}
+
+/** Replaces each placeholder with a Babel AST expression while transforming the module through Oxc. */
+export async function replaceWithAst(
+    code: string,
+    filename: string,
+    replacement: Readonly<Record<string, Parameters<typeof generate>[0]>>,
+    sourcemap = true
+): Promise<AstTransformResult> {
+    const define: Record<string, string> = {}
+
+    for (const [placeholder, node] of Object.entries(replacement)) {
+        requireOnePlaceholder(code, placeholder)
+        define[placeholder] = ast2str(node)
+    }
+
+    const transformed = await transformWithOxc(code, filename, { define, sourcemap, target: esTarget })
+
+    for (const placeholder of Object.keys(replacement)) {
+        if (transformed.code.includes(placeholder)) {
+            throw new Error(`Failed to replace placeholder ${placeholder} in ${filename}`)
+        }
+    }
+    if (sourcemap && !transformed.map) {
+        throw new Error(`Failed to generate a source map for ${filename}`)
+    }
+
+    return {
+        code: transformed.code,
+        map: sourcemap ? (transformed.map ?? null) : null
+    }
+}
+
+/** Serializes a Babel AST node as a compact expression for Oxc substitution. */
+function ast2str(node: Parameters<typeof generate>[0]): string {
+    return generate(node, { comments: false, compact: true, concise: true, minified: true }).code
+}
+
+/** Validates exactly one placeholder before Babel expression substitution. */
+function requireOnePlaceholder(code: string, placeholder: string): void {
+    const replacementCount = code.split(placeholder).length - 1
+    if (replacementCount !== 1) {
+        throw new Error(`Expected one placeholder ${placeholder}, found ${replacementCount}`)
+    }
+}
+
+/** Transforms one module with Babel's shared parser and source-map configuration. */
+export function transformWithBabel(
+    code: string,
+    filename: string,
+    plugins: PluginItem[],
+    sourcemap = true
+): AstTransformResult {
+    const transformed = transformSync(code, {
+        babelrc: false,
+        compact: true,
+        minified: true,
+        comments: false,
+        configFile: false,
+        filename,
+        plugins,
+        sourceFileName: filename,
+        sourceMaps: sourcemap,
+        sourceType: 'module'
+    })
+    if (!transformed?.code || (sourcemap && !transformed.map)) {
+        throw new Error(`Failed to transform ${filename} with Babel`)
+    }
+
+    return {
+        code: transformed.code,
+        map: sourcemap ? (transformed.map as Rolldown.ExistingRawSourceMap) : null
+    }
+}

package/src/node/vite-plugin.ts

@@ -1,40 +1,20 @@
 import react from '@vitejs/plugin-react'
-import type { Plugin, PluginOption } from 'vite'
+import type { PluginOption } from 'vite'
 import type { VitePluginTaroOptions } from '../options.ts'
-import { BuildContext } from './build-context.ts'
-import { createConditionalDirectivePlugin } from './plugins/conditional-directives.ts'
-import { createTaroRuntimePlugin } from './plugins/taro-runtime.ts'
-import { createH5TargetPlugins, createH5ViteConfig } from './targets/h5/plugin.ts'
-import { createWxTargetPlugins, createWxViteConfig } from './targets/wx/plugin.ts'
+import { createClientTaroPlugin } from './plugins/client/client-taro.ts'
+import { createConditionalDirectivePlugin } from './plugins/conditional/conditional-directives.ts'
+import { createCssPlugins } from './plugins/css/plugins.ts'
+import { createH5TargetPlugins } from './plugins/h5/plugins.ts'
+import { createWxTargetPlugins } from './plugins/wx/plugins.ts'
 
-/** Creates the Vite plugins for the selected Taro target. */
+/** Creates the Vite plugins for one Taro target. */
 export default function vitePluginTaro(options: VitePluginTaroOptions): PluginOption[] {
-    const context = new BuildContext(options)
-
     return [
-        createBuildCoordinator(context),
-        createConditionalDirectivePlugin(context),
-        createTaroRuntimePlugin(),
-        ...context.css.plugins,
+        createConditionalDirectivePlugin(options.target),
+        createClientTaroPlugin(),
+        ...createCssPlugins(options.target),
         ...react(),
-        ...(context.project.target === 'wx' ? createWxTargetPlugins(context) : []),
-        ...(context.project.target === 'h5' ? createH5TargetPlugins(context) : [])
+        ...(options.target === 'wx' ? createWxTargetPlugins(options) : []),
+        ...(options.target === 'h5' ? createH5TargetPlugins(options) : [])
     ]
 }
-
-/** Establishes build mode and resolved Vite state before target hooks consume the context. */
-function createBuildCoordinator(context: BuildContext): Plugin {
-    return {
-        name: 'vite-plugin-taro:build',
-        enforce: 'pre',
-
-        config(_, environment) {
-            context.configure(environment)
-            return context.project.target === 'wx' ? createWxViteConfig(context) : createH5ViteConfig(context)
-        },
-
-        configResolved(config) {
-            context.resolve(config)
-        }
-    }
-}

package/src/options.ts

@@ -1,19 +1,18 @@
-/** Plain JSON object emitted into Mini Program/Web config payloads. */
+/** A JSON object used by generated target configs. */
 export type JsonObject = Record<string, unknown>
 
 /** Build target handled by this plugin. */
 export type VitePluginTaroTarget = 'wx' | 'h5'
 
-/** Describes one React-backed page shared by WeChat Mini Program and Web builds. */
+/** Configures one Taro page. */
 export type VitePluginTaroPageOption = {
     /** Taro route and output path without a file extension. */
     path: string
 
-    /** Page config merged into the generated target config. */
     config: JsonObject
 }
 
-/** Required build inputs for the Vite/Rolldown Taro renderer plugin. */
+/** Configures the Vite Taro plugin. */
 export interface VitePluginTaroOptions {
     target: VitePluginTaroTarget
     app: string

package/src/runtime/client/taro/api.ts

@@ -0,0 +1,11 @@
+import '@tarojs/plugin-framework-react/dist/runtime'
+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 the facade also exposes its runtime named exports.
+export * from '@tarojs/taro'
+export default Taro

package/src/runtime/client/taro/component.ts

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

package/src/runtime/client/taro/define-native-component.ts

@@ -0,0 +1,15 @@
+import type { ComponentType, PropsWithChildren } from 'react'
+
+export type NativeComponentEvent<Detail> = {
+    readonly detail: Detail
+}
+
+/** Defines a typed JSX interface from a static `() => import('./relative-entry.js')` reference. */
+export function defineNativeComponent(loadEntry: () => Promise<unknown>): ComponentType<PropsWithChildren>
+export function defineNativeComponent<const Props extends object>(
+    loadEntry: () => Promise<unknown>
+): ComponentType<PropsWithChildren<Props>>
+export function defineNativeComponent(loadEntry: () => Promise<unknown>): never {
+    void loadEntry
+    throw new Error('Native component interface was not compiled')
+}

package/src/runtime/h5/app.ts

@@ -0,0 +1,25 @@
+/** biome-ignore-all assist/source/organizeImports: keep side effect orders */
+
+import { createHashHistory, createReactApp, createRouter, handleAppMount, window } from './taro-runtime.ts'
+import type { Route, SpaRouterConfig } from '@tarojs/router/types/router'
+import React from 'react'
+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[]
+
+const browserWindow = window as unknown as Window &
+    typeof window & {
+        __taroAppConfig: SpaRouterConfig
+    }
+const config = __VITE_PLUGIN_TARO_H5_APP_CONFIG__
+browserWindow.__taroAppConfig = config
+config.routes = __VITE_PLUGIN_TARO_H5_ROUTES__
+const app = createReactApp(AppComponent, React, ReactDOM, config)
+const history = createHashHistory({ window: browserWindow })
+handleAppMount(config, history)
+// @ts-expect-error Taro's implementation receives the React adapter object despite declaring a string.
+createRouter(history, app, config, React)

package/src/runtime/h5/taro-runtime.ts

@@ -2,9 +2,6 @@
 import '@tarojs/components/global.css'
 import '@tarojs/components/dist/taro-components/taro-components.css'
 
-// Import the CSS files directly instead of @tarojs/plugin-platform-h5/dist/runtime:
-// that runtime adds only taro-components.css plus optional polyfills, while generated H5 entries also need 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 { createHashHistory, createRouter, handleAppMount } from '@tarojs/router'
 export { window } from '@tarojs/runtime'

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

@@ -0,0 +1,22 @@
+// Install the minimal SystemJS loader and its synchronous-import extension before any native entry requests a capsule.
+import '../systemjs/system-core.js'
+import { transport } from './transport.ts'
+
+declare const __VITE_PLUGIN_TARO_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__
+
+// 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.
+export const __vitePreload = <Value>(load: () => Value): Value => load()
+
+// SystemJS installs on WeChat's `global` object; its properties are not lexical bindings.
+const installedSystem = (global as unknown as WeChatGlobal & { System: System.Loader }).System
+if (!installedSystem) {
+    throw new Error('SystemJS failed to initialize in the WeChat runtime')
+}
+
+// Transport returns synchronous registrations for main-package capsules and amphibious modules, and promise-like
+// registrations only for capsules that physically live in generated subpackages.
+installedSystem.instantiate = transport

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

@@ -0,0 +1,10 @@
+// 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.
+
+/** Materialized from the preliminary output graph before Rolldown finalizes content hashes. */
+declare const __VITE_PLUGIN_TARO_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__

package/src/runtime/wx/capsule/app.ts

@@ -0,0 +1,9 @@
+// biome-ignore assist/source/organizeImports: Taro must initialize before the App component.
+import { createReactApp, ReactDOM } from './taro-runtime.ts'
+import React from 'react'
+import { appConfig } from '../amphibious/bootstrap.ts'
+
+// @ts-expect-error: The wx build resolves this private App component.
+import AppComponent from '\0vpt:app-component'
+
+export default createReactApp(AppComponent, React, ReactDOM, appConfig)

package/src/runtime/wx/capsule/component.ts

@@ -0,0 +1,6 @@
+// Keep recursive Component activation behind the same App initialization barrier as Page activation.
+import './app.ts'
+
+import { createRecursiveComponentConfig } from './taro-runtime.ts'
+
+export default createRecursiveComponentConfig('comp')

package/src/runtime/wx/capsule/page.ts

@@ -0,0 +1,96 @@
+// App and Page shells activate independently; make Current.app initialization an explicit prerequisite for Page mount.
+import './app.ts'
+
+// @ts-expect-error: The wx build replaces this private import with the configured Page component.
+import PageComponent from '\0vpt:page-component'
+import { Current, createPageConfig, document, injectPageInstance } from './taro-runtime.ts'
+
+declare const __VITE_PLUGIN_TARO_PAGE_PATH__: string
+declare const __VITE_PLUGIN_TARO_PAGE_CONFIG__: Record<string, unknown>
+
+const config = createPageConfig(
+    PageComponent,
+    __VITE_PLUGIN_TARO_PAGE_PATH__,
+    { root: { cn: [] } },
+    __VITE_PLUGIN_TARO_PAGE_CONFIG__
+)
+
+export default config
+
+// HMR
+
+type LifecycleHandler = (this: unknown, ...args: unknown[]) => void
+
+/** Forwards a call with the native page instance as `this`, matching Taro's invocation. */
+function forward(handler: unknown, receiver: unknown, args: unknown[]): void {
+    ;(handler as LifecycleHandler | undefined)?.apply(receiver, args)
+}
+
+/** The surviving page identity: its unique path and params. */
+type PageIdentity = {
+    $taroPath: string
+    $taroParams: Record<string, unknown>
+}
+
+// DevTools re-executes the page and replays the replacement lifecycle on every edit. Taro's
+// onUnload unmounts the React tree and onLoad mounts a fresh one, destroying state. While
+// the runtime says a patch was just delivered, the pair is intercepted instead: onUnload
+// captures the surviving page identity, and onLoad restores it onto the replacement native
+// instance and rebinds the retained tree to it (pageElement.ctx + a full re-render). The
+// capsule module is cached across re-executions, so this closure holds the capture.
+// Ordinary navigation (no patch) passes through unchanged. The wrappers are regular
+// functions so the native page instance (`this`) reaches the original handlers.
+if (typeof __rolldown_runtime__ !== 'undefined') {
+    const originalOnUnload = config.onUnload
+    const originalOnLoad = config.onLoad
+    const originalOnShow = config.onShow
+
+    let captured: PageIdentity | undefined
+
+    config.onUnload = function (this: unknown, ...args: unknown[]) {
+        if (__rolldown_runtime__.isHotReloading()) {
+            const instance = this as unknown as PageIdentity
+            captured = {
+                $taroPath: instance.$taroPath,
+                $taroParams: instance.$taroParams
+            }
+            return
+        }
+        forward(originalOnUnload, this, args)
+    }
+    config.onLoad = function (this: unknown, ...args: unknown[]) {
+        if (__rolldown_runtime__.isHotReloading() && captured) {
+            // Restore the surviving page identity onto the replacement native instance: the
+            // re-loaded $taroPath embeds a fresh timestamp, so without this the tree and the
+            // native side would disagree on the page key.
+            const instance = this as unknown as PageIdentity
+            instance.$taroPath = captured.$taroPath
+            instance.$taroParams = captured.$taroParams
+            // Rebind the retained tree to the replacement receiver and resync the native
+            // data: updateChildNodes enqueues the full hydrated node tree (root.cn) — the
+            // surviving tree's mutations were consumed long ago, so without it the payload
+            // queue is empty and the new receiver renders nothing.
+            injectPageInstance(instance as unknown as Parameters<typeof injectPageInstance>[0], captured.$taroPath)
+            Current.page = instance as unknown as typeof Current.page
+            const pageElement = document.getElementById(captured.$taroPath) as unknown as {
+                ctx: unknown
+                updateChildNodes: () => void
+                performUpdate: (initRender?: boolean) => void
+            }
+            pageElement.ctx = instance
+            pageElement.updateChildNodes()
+            pageElement.performUpdate(true)
+            return
+        }
+        forward(originalOnLoad, this, args)
+    }
+    config.onShow = function (this: unknown, ...args: unknown[]) {
+        if (__rolldown_runtime__.isHotReloading()) {
+            // The window ends at the first show; the user's onShow must not re-run on a
+            // synthetic re-execution (it could reset state).
+            __rolldown_runtime__.clearHotReloading()
+            return
+        }
+        forward(originalOnShow, this, args)
+    }
+}

package/src/runtime/wx/capsule/taro-runtime.ts

@@ -0,0 +1,14 @@
+/** biome-ignore-all assist/source/organizeImports: keep side effect orders */
+
+/** Taro runtime exports shared by the App, Page, and recursive Component capsules. */
+import '@tarojs/plugin-platform-weapp/dist/runtime.js'
+
+export { createReactApp } from '@tarojs/plugin-framework-react/dist/runtime'
+export { default as ReactDOM } from '@tarojs/react'
+export {
+    createPageConfig,
+    createRecursiveComponentConfig,
+    Current,
+    document,
+    injectPageInstance
+} from '@tarojs/runtime'