vite-plugin-taro 0.3.2 → 0.4.0

package/src/node/plugins/wx/dev/react-refresh.ts

@@ -0,0 +1,227 @@
+import { type PluginObject, types } from '@babel/core'
+import type { Plugin } from 'vite'
+import { memoize } from '../../../utils/memoize.ts'
+import { transformWithBabel } from '../../../utils/transform.ts'
+
+/** The React DevTools hook protocol name; free references must target `global` in wx. */
+const reactDevtoolsHookProtocol = '__REACT_DEVTOOLS_GLOBAL_HOOK__'
+
+/**
+ * Creates the serve-only React Refresh adaptation transforms for the wx target.
+ *
+ * @vitejs/plugin-react's generated refresh code assumes the web HTML preamble and a browser
+ * global scope; wx has neither. Each transform adapts one piece of that contract:
+ * - the refresh runtime module (id-filtered): the vendored runtime reads and assigns
+ *   `window` protocol globals (rewritten to `global`) and must inject itself at evaluation
+ *   — the preamble's `injectIntoGlobalHook` call has no HTML home in wx;
+ * - react-family modules (filtered on free references): the DevTools hook is read as a free
+ *   variable, which the WeChat runtime scope never resolves against `global` — every free
+ *   reference becomes an explicit member access;
+ * - boundary modules (filtered on the guard): the preamble's `$RefreshReg$` global is not
+ *   needed because the transform generates local wrappers over the imported refresh
+ *   runtime, so the guard that checks for the global is removed.
+ *
+ * Each transform's filter is its routing: the three domains are disjoint, so a module is
+ * transformed by at most one of them, and modules outside all three never reach a handler.
+ */
+export function createWxReactRefreshTransforms(): Plugin[] {
+    return [
+        {
+            name: 'vpt:wx-react-refresh-runtime',
+            apply: 'serve',
+            transform: {
+                order: 'post',
+                // The vendored refresh runtime module; id-filtered, so no code scan.
+                filter: { id: /^\/@react-refresh(?:\?|$)/ },
+                handler(code, id) {
+                    return fixRefreshRuntime({ code, id })
+                }
+            }
+        },
+        {
+            name: 'vpt:wx-react-devtools-hook',
+            apply: 'serve',
+            transform: {
+                order: 'post',
+                // Matches only free references (react-family modules). The member accesses in
+                // the refresh runtime and the dev runtime chunk never match, so they need no
+                // id exclusion.
+                filter: { code: /(^|[^.\w$])__REACT_DEVTOOLS_GLOBAL_HOOK__/ },
+                handler(code, id) {
+                    return fixReactDevtoolsHook({ code, id })
+                }
+            }
+        },
+        {
+            name: 'vpt:wx-refresh-preamble-guard',
+            apply: 'serve',
+            transform: {
+                order: 'post',
+                // Vite's documented refresh protocol global; the generated guard is its only
+                // occurrence, in boundary modules.
+                filter: { code: /window\.\$RefreshReg\$/ },
+                handler(code, id) {
+                    return transformWithBabel(code, id, [removeRefreshPreambleGuard], false)
+                }
+            }
+        }
+    ]
+}
+
+/**
+ * React-family modules: free `__REACT_DEVTOOLS_GLOBAL_HOOK__` reads must target `global`.
+ *
+ * The renderer checks the hook with `typeof __REACT_DEVTOOLS_GLOBAL_HOOK__` and injects via
+ * `hook.inject(...)` — but in the WeChat runtime, free-variable reads never resolve against
+ * `global`'s properties (verified: the free lookup is undefined while
+ * `global.__REACT_DEVTOOLS_GLOBAL_HOOK__` exists), so the renderer would silently skip
+ * injection and React Refresh would have no renderer to schedule re-renders on.
+ *
+ * The name is unique to the React DevTools protocol, so rewriting every free reference to an
+ * explicit member access is precise. The hook itself is created on `global` by the dev
+ * runtime chunk (see dev-runtime.ts).
+ */
+function rewriteReactDevtoolsHookGlobal(): PluginObject {
+    return {
+        name: 'vpt:wx-react-devtools-hook-global',
+        visitor: {
+            Identifier(identifierPath) {
+                const node = identifierPath.node
+                if (!types.isIdentifier(node, { name: reactDevtoolsHookProtocol })) {
+                    return
+                }
+                const parent = identifierPath.parentPath
+                // A member expression property (e.g. `global.__REACT_DEVTOOLS_GLOBAL_HOOK__`)
+                // is already explicit and must not be rewritten again.
+                if (parent.isMemberExpression() && parent.node.property === node) {
+                    return
+                }
+                identifierPath.replaceWith(
+                    types.memberExpression(types.identifier('global'), types.identifier(node.name))
+                )
+            }
+        }
+    }
+}
+
+/**
+ * Refresh runtime module: self-inject at evaluation — the wx App heap has no HTML preamble.
+ *
+ * In web Vite, the HTML preamble calls `injectIntoGlobalHook(window)` before any module
+ * loads; nothing does that in wx. The call must live in this module itself:
+ * - its closure owns the refresh state (helpersByRendererID, mountedRoots), so the same
+ *   instance that the generated boundary code imports must bootstrap itself;
+ * - the dev runtime chunk cannot reach it: the module is in a lazily-loaded chunk that
+ *   requires the runtime chunk first, so it does not exist when the runtime evaluates.
+ *
+ * Unlike the preamble's `$RefreshReg$` globals (removed by removeRefreshPreambleGuard
+ * because boundary modules define local wrappers), the hook machinery has no local
+ * equivalent — without it the refresh runtime never learns the renderer or the mounted
+ * roots, so the injection is the one preamble responsibility that must be replicated.
+ *
+ * Timing is safe because injectIntoGlobalHook replays hook.renderers: the renderer already
+ * injected into the hook (created by the dev runtime chunk) when the App mounted, and the
+ * replay captures it; the patched commit hooks then track every later mount, including the
+ * remounts on re-execution.
+ */
+function injectRefreshGlobalHook(): PluginObject {
+    return {
+        name: 'vpt:wx-refresh-global-hook-injection',
+        visitor: {
+            Program(programPath) {
+                // The renderer already injected into the hook (created by the dev runtime
+                // chunk) when the App mounted; injectIntoGlobalHook replays its renderers.
+                programPath.pushContainer(
+                    'body',
+                    types.expressionStatement(
+                        types.callExpression(types.identifier('injectIntoGlobalHook'), [types.identifier('global')])
+                    )
+                )
+            }
+        }
+    }
+}
+
+/**
+ * Refresh runtime module: rewrites the generated `window.<protocol>` accesses to `global`.
+ *
+ * The vendored refresh runtime is written for browsers and uses `window` for its protocol
+ * globals, but the WeChat runtime has no `window` — the free identifier is undefined — so the
+ * top-level assignment would throw at module evaluation, and the ignored-exports read
+ * inside the refresh validator would crash every update pass.
+ *
+ * Only the exact known protocol names are rewritten, one by one, so unrelated `window`
+ * accesses are never touched and future protocol additions are deliberate.
+ */
+function rewriteRefreshRuntimeWindowAccess(): PluginObject {
+    /**
+     * Refresh protocol globals that must land on the WeChat `global`:
+     * - `__registerBeforePerformReactRefresh`: assigned at module scope; in web, the HMR
+     *   client registers pre-refresh callbacks through it — the assignment throws on
+     *   undefined `window`;
+     * - `__getReactRefreshIgnoredExports`: read in validateRefreshBoundaryAndEnqueueUpdate
+     *   as an optional extension point — a read on undefined `window` crashes.
+     */
+    const refreshRuntimeWindowGlobals = ['__registerBeforePerformReactRefresh', '__getReactRefreshIgnoredExports']
+
+    return {
+        name: 'vpt:wx-refresh-runtime-window-access',
+        visitor: {
+            MemberExpression(memberPath) {
+                const member = memberPath.node
+                if (
+                    !types.isIdentifier(member.object, { name: 'window' }) ||
+                    !types.isIdentifier(member.property) ||
+                    !refreshRuntimeWindowGlobals.includes(member.property.name)
+                ) {
+                    return
+                }
+                // `global` is the WeChat global object — the same one the hook injection
+                // and the rest of the wx glue speak — so the protocol globals land on the
+                // App heap like any other global hook.
+                member.object = types.identifier('global')
+            }
+        }
+    }
+}
+
+/** Boundary modules: remove the generated `if (!window.$RefreshReg$) throw Error(...)` guard. */
+function removeRefreshPreambleGuard(): PluginObject {
+    return {
+        name: 'vpt:wx-refresh-preamble-guard',
+        visitor: {
+            IfStatement(ifPath) {
+                // The guard is a web-only sanity check that the HTML preamble installed the
+                // `$RefreshReg$` global. wx has no preamble and no such global — but the
+                // boundary module does not need it: the plugin transform generates local
+                // `$RefreshReg$`/`$RefreshSig$` wrappers that delegate to the imported
+                // refresh runtime, so registration works without the global. The guard
+                // itself only crashes on the undefined `window`, so it is removed.
+                const test = ifPath.node.test
+                if (
+                    types.isUnaryExpression(test, { operator: '!' }) &&
+                    types.isMemberExpression(test.argument) &&
+                    types.isIdentifier(test.argument.object, { name: 'window' }) &&
+                    types.isIdentifier(test.argument.property, { name: '$RefreshReg$' })
+                ) {
+                    ifPath.remove()
+                }
+            }
+        }
+    }
+}
+
+// The refresh runtime module and the react-family modules are immutable for the server's
+// lifetime (they only change when the plugin is rebuilt), so their Babel transforms run once
+// per module and every build reuses the output.
+const fixRefreshRuntime = memoize(
+    ({ code, id }: { code: string; id: string }) =>
+        transformWithBabel(code, id, [rewriteRefreshRuntimeWindowAccess, injectRefreshGlobalHook], false),
+    { getCacheKey: ({ code }) => code }
+)
+
+const fixReactDevtoolsHook = memoize(
+    ({ code, id }: { code: string; id: string }) =>
+        transformWithBabel(code, id, [rewriteReactDevtoolsHookGlobal], false),
+    { getCacheKey: ({ code }) => code }
+)

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

@@ -0,0 +1,97 @@
+import path from 'node:path'
+import type { Rolldown } from 'vite'
+import { normalizeModuleId } from '../../utils/modules.ts'
+import { packageRequire, resolvePackageFile } from '../../utils/packages.ts'
+
+/** Identifies Rolldown's generated helper module independently of its unstable output filename. */
+export const rolldownRuntimeId = '\0rolldown/runtime.js'
+
+/** Resolves the direct React Reconciler dependency without assuming pnpm's layout. */
+export const reactReconcilerRoot = normalizeModuleId(
+    path.dirname(packageRequire.resolve('react-reconciler/package.json'))
+)
+
+/** Identifies the amphibious bootstrap that initializes SystemJS and serves every native shell. */
+export const bootstrapPath = resolvePackageFile('dist/runtime/wx/amphibious/bootstrap.js')
+
+/** Identifies the native transport source materialized before Rolldown finalizes content hashes. */
+export const transportPath = resolvePackageFile('dist/runtime/wx/amphibious/transport.js')
+
+/** Redirects Vite's injected browser preload helper to the bootstrap identity loader. */
+export const vitePreloadId = '\0vite/preload-helper.js'
+
+/** Forces the native App shell entry to emit at WeChat's required root path. */
+export const appShellFileName = 'app.js'
+
+/** Identifies the synchronous native App shell source. */
+export const appShellPath = resolvePackageFile('dist/runtime/wx/native/app.js')
+
+/** Identifies the App capsule kept behind the native shell boundary. */
+export const appCapsulePath = resolvePackageFile('dist/runtime/wx/capsule/app.js')
+
+/** Forces Taro's recursive native Component entry to emit at its configured root path. */
+export const componentShellFileName = 'comp.js'
+
+/** Identifies the synchronous recursive Component shell source. */
+export const componentShellPath = resolvePackageFile('dist/runtime/wx/native/component.js')
+
+/** Identifies the recursive Component capsule kept behind the native shell boundary. */
+export const componentCapsulePath = resolvePackageFile('dist/runtime/wx/capsule/component.js')
+
+/** Resolves the configured Page component from its route-qualified capsule importer. */
+export const pageComponentId = '\0vpt:page-component'
+
+/** Gives every Page shell one private capsule target that can be resolved using its route. */
+export const pageCapsuleId = '\0vpt:page-capsule'
+
+/** Provides the Page capsule source specialized through a stable route query. */
+export const pageCapsulePath = resolvePackageFile('dist/runtime/wx/capsule/page.js')
+
+/** Identifies the reusable synchronous native Page shell source. */
+export const pageShellPath = resolvePackageFile('dist/runtime/wx/native/page.js')
+
+export type WxChunk = Rolldown.PreRenderedChunk | Rolldown.RenderedChunk
+
+/** Build-graph role of an explicit native lifecycle entry. */
+export type WxEntryRole = 'shell' | 'capsule'
+
+/** Runtime domain in which one final wx JavaScript chunk executes. */
+export type WxExecutionKind = 'native' | 'capsule' | 'amphibious'
+
+// These fixed source identities describe entry roles independently from the final execution kind. A capsule entry may,
+// for example, become amphibious when Rolldown coalesces its generated runtime into the same output chunk.
+const shellModuleIds: ReadonlySet<string> = new Set([appShellPath, componentShellPath, pageShellPath])
+const capsuleModuleIds: ReadonlySet<string> = new Set([appCapsulePath, componentCapsulePath, pageCapsulePath])
+const amphibiousModuleIds: ReadonlySet<string> = new Set([bootstrapPath, rolldownRuntimeId])
+
+/** Returns the one explicit lifecycle role owned by a chunk. */
+export function getWxEntryRole(chunk: WxChunk): WxEntryRole | undefined {
+    const ownsShell = containsModule(chunk, shellModuleIds)
+    const ownsCapsule = containsModule(chunk, capsuleModuleIds)
+    if (ownsShell && ownsCapsule) {
+        throw new Error(`wx chunk mixes shell and capsule entries: ${chunk.moduleIds.join(', ')}`)
+    }
+    return ownsShell ? 'shell' : ownsCapsule ? 'capsule' : undefined
+}
+
+/** Tests whether a chunk contains the physical transport implementation. */
+export function isTransportModule(chunk: WxChunk): boolean {
+    return chunk.moduleIds.includes(transportPath)
+}
+
+/**
+ * Classifies one final output chunk by execution domain. Entry role is deliberately independent: explicit capsule entries
+ * normally fall through to capsule rendering, but a capsule containing an amphibious runtime executes in both domains.
+ */
+export function getWxExecutionKind(chunk: WxChunk): WxExecutionKind {
+    const entryRole = getWxEntryRole(chunk)
+    if (containsModule(chunk, amphibiousModuleIds)) {
+        return 'amphibious'
+    }
+    return entryRole === 'shell' || isTransportModule(chunk) ? 'native' : 'capsule'
+}
+
+/** Tests normalized chunk module IDs against one fixed identity set. */
+function containsModule(chunk: WxChunk, moduleIds: ReadonlySet<string>): boolean {
+    return chunk.moduleIds.some((moduleId) => moduleIds.has(normalizeModuleId(moduleId)))
+}

package/src/node/plugins/wx/native/compile-native-component-interface.ts

@@ -0,0 +1,47 @@
+import path from 'node:path'
+import { normalizeModuleId } from '../../../utils/modules.ts'
+import { collectNativeComponentAssets, nativeComponentMetaKey } from './native-component-assets.ts'
+import { transformNativeComponentInterfaces } from './native-component-interface.ts'
+
+/** Compiles one JSX interface module and attaches its opaque native sources to Rolldown metadata. */
+export async function compileNativeComponentInterface({
+    code,
+    id,
+    sourcemap,
+    addWatchFile
+}: {
+    code: string
+    id: string
+    sourcemap: boolean
+    addWatchFile: (file: string) => void
+}) {
+    const transformed = transformNativeComponentInterfaces(code, id, sourcemap)
+    const interfacePath = normalizeModuleId(id)
+
+    const nativeComponents = await Promise.all(
+        transformed.definitions.map((definition) => collectNativeComponentAssets(definition, interfacePath))
+    )
+
+    nativeComponents.forEach((source) => {
+        addWatchFile(source.folder)
+
+        source.assets.forEach((asset) => {
+            addWatchFile(path.join(source.folder, asset.relativePath))
+        })
+    })
+
+    const assetBytes = nativeComponents.reduce((sourceTotal, source) => {
+        return sourceTotal + source.assets.reduce((assetTotal, asset) => assetTotal + asset.byteLength, 0)
+    }, 0)
+
+    return {
+        code: transformed.code,
+        map: transformed.map,
+        meta: {
+            [nativeComponentMetaKey]: {
+                sources: nativeComponents,
+                assetBytes
+            }
+        }
+    }
+}

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

@@ -0,0 +1,57 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import type { Rolldown } from 'vite'
+import { isGeneratedSubpackageFile } from '../placement/plan.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
+}: {
+    bundle: Rolldown.OutputBundle
+    getModuleInfo: (moduleId: string) => { meta: Rolldown.CustomPluginOptions } | null
+}) {
+    // Files and registrations accumulate in final chunk order for deterministic output.
+    const files: Rolldown.EmittedAsset[] = []
+
+    const registrations: {
+        name: string
+        componentPath: string
+        fields: readonly string[]
+    }[] = []
+
+    for (const output of Object.values(bundle)) {
+        if (output.type !== 'chunk') {
+            continue
+        }
+        const packageRoot = isGeneratedSubpackageFile(output.fileName)
+            ? path.posix.dirname(path.posix.dirname(output.fileName))
+            : undefined
+
+        for (const moduleId of output.moduleIds) {
+            const sources = getNativeComponentSources(getModuleInfo(moduleId)?.meta)
+            for (const source of sources) {
+                const name = path.posix.basename(source.folder)
+                const componentFolder = path.posix.join('components', name)
+                const outputFolder = packageRoot ? path.posix.join(packageRoot, componentFolder) : componentFolder
+
+                registrations.push({
+                    name,
+                    componentPath: `/${path.posix.join(outputFolder, source.entry)}`,
+                    fields: source.fields
+                })
+
+                for (const asset of source.assets) {
+                    files.push({
+                        type: 'asset',
+                        fileName: path.posix.join(outputFolder, asset.relativePath),
+                        source: await readFile(path.join(source.folder, asset.relativePath))
+                    })
+                }
+            }
+        }
+    }
+
+    return { files, registrations }
+}

package/src/node/plugins/wx/native/native-component-assets.ts

@@ -0,0 +1,114 @@
+import { readdir, stat } from 'node:fs/promises'
+import path from 'node:path'
+import type { Rolldown } from 'vite'
+import { normalizeModuleId } from '../../../utils/modules.ts'
+import type { NativeComponentDefinition } from './native-component-interface.ts'
+
+type NativeComponentAsset = {
+    relativePath: string
+    byteLength: number
+}
+
+export const nativeComponentMetaKey = 'vpt:native-components'
+
+type NativeComponentSource = NativeComponentDefinition & {
+    assets: readonly NativeComponentAsset[]
+}
+
+type NativeComponentMetadata = {
+    sources: readonly NativeComponentSource[]
+    assetBytes: number
+}
+
+declare module 'rolldown' {
+    interface CustomPluginOptions {
+        [nativeComponentMetaKey]?: NativeComponentMetadata
+    }
+}
+
+/** Reads the native contribution to a transformed module's package weight. */
+export function getNativeComponentAssetBytes(meta: Rolldown.CustomPluginOptions | undefined): number {
+    return meta?.[nativeComponentMetaKey]?.assetBytes ?? 0
+}
+
+/** Reads native sources attached to one transformed JSX interface module. */
+export function getNativeComponentSources(meta: Rolldown.CustomPluginOptions | undefined) {
+    return meta?.[nativeComponentMetaKey]?.sources ?? []
+}
+
+/** Collects a native component folder as opaque, recursively ordered assets without copying its interface module. */
+export async function collectNativeComponentAssets(
+    definition: NativeComponentDefinition,
+    interfacePath: string
+): Promise<NativeComponentSource> {
+    await requireNativeComponentDirectory(definition.folder)
+    await requireNativeComponentEntry(definition)
+
+    // This mutable accumulator is local to one traversal and avoids repeatedly copying growing asset arrays.
+    const assets: NativeComponentAsset[] = []
+    await collectDirectory(definition.folder, [], assets, normalizeModuleId(interfacePath))
+
+    return { ...definition, assets }
+}
+
+/** Rejects a missing or non-directory source before Rolldown starts its recursive traversal. */
+async function requireNativeComponentDirectory(folder: string): Promise<void> {
+    try {
+        if ((await stat(folder)).isDirectory()) {
+            return
+        }
+    } catch (error) {
+        if (Error.isError(error) && 'code' in error && error.code === 'ENOENT') {
+            throw new Error(`Native component folder does not exist: ${folder}`, { cause: error })
+        }
+        throw error
+    }
+    throw new Error(`Native component source is not a directory: ${folder}`)
+}
+
+/** Rejects a missing or non-file JavaScript entry before native output registration. */
+async function requireNativeComponentEntry(definition: NativeComponentDefinition): Promise<void> {
+    const entryPath = path.join(definition.folder, `${definition.entry}.js`)
+    try {
+        if ((await stat(entryPath)).isFile()) {
+            return
+        }
+    } catch (error) {
+        if (Error.isError(error) && 'code' in error && error.code === 'ENOENT') {
+            throw new Error(`Native component entry file does not exist: ${entryPath}`, { cause: error })
+        }
+        throw error
+    }
+    throw new Error(`Native component entry is not a file: ${entryPath}`)
+}
+
+/** Traverses entries lexically so output remains deterministic across filesystems. */
+async function collectDirectory(
+    folder: string,
+    segments: readonly string[],
+    assets: NativeComponentAsset[],
+    interfacePath: string
+): Promise<void> {
+    const directory = path.join(folder, ...segments)
+    const entries = await readdir(directory, { withFileTypes: true })
+    entries.sort((left, right) => left.name.localeCompare(right.name))
+
+    for (const entry of entries) {
+        const entrySegments = [...segments, entry.name]
+        if (entry.isDirectory()) {
+            await collectDirectory(folder, entrySegments, assets, interfacePath)
+            continue
+        }
+        if (!entry.isFile()) {
+            continue
+        }
+        const sourcePath = path.join(folder, ...entrySegments)
+        if (normalizeModuleId(sourcePath) === interfacePath) {
+            continue
+        }
+        assets.push({
+            relativePath: entrySegments.join('/'),
+            byteLength: (await stat(sourcePath)).size
+        })
+    }
+}