vite-plugin-taro 0.2.2 → 0.3.0

package/src/node/targets/wx/plugin.ts

@@ -0,0 +1,163 @@
+import path from 'node:path'
+import type { Plugin, PluginOption, UserConfig } from 'vite'
+import type { BuildContext } from '../../build-context.ts'
+import { normalizeModuleId, stripVirtualPrefix } from '../../utils/modules.ts'
+import { packageRequire } from '../../utils/packages.ts'
+import { emitWxCompanionAssets, type WxBundle } from './companion-assets.ts'
+import { WxDevelopmentSession } from './dev-server/development-session.ts'
+import { transformWxReactRefreshModule } from './react-refresh.ts'
+import { emitWxEntryChunks, isWxVirtualModuleId, loadWxVirtualModule, virtualWxAppId } from './virtual-modules.ts'
+
+const taroWxComponentsPath = packageRequire.resolve('@tarojs/plugin-platform-weapp/dist/components-react')
+const vitePluginTaroSourcePath = normalizeModuleId(path.dirname(packageRequire.resolve('vite-plugin-taro')))
+const taroVersion = String(packageRequire('@tarojs/runtime/package.json').version)
+
+/** Creates the plugins that own the complete WX build and development lifecycle. */
+export function createWxTargetPlugins(context: BuildContext): PluginOption[] {
+    return [createWxTargetPlugin(context)]
+}
+
+function createWxTargetPlugin(context: BuildContext): Plugin {
+    let developmentSession: WxDevelopmentSession | undefined
+
+    return {
+        name: 'vite-plugin-taro:wx',
+
+        resolveId: {
+            order: 'pre',
+            handler(id) {
+                return isWxVirtualModuleId(id) ? `\0${id}` : undefined
+            }
+        },
+
+        load: {
+            order: 'post',
+            handler(id) {
+                const cleanId = stripVirtualPrefix(id)
+
+                emitWxEntryChunks(this, context, cleanId)
+
+                return loadWxVirtualModule(cleanId, context)
+            }
+        },
+
+        transform: {
+            order: 'post',
+            async handler(code, id) {
+                if (!context.development) return
+
+                const transformed = await transformWxReactRefreshModule(code, id, context.project.appComponentFile)
+                return transformed === code ? undefined : transformed
+            }
+        },
+
+        generateBundle: {
+            order: 'post',
+            handler(_, bundle) {
+                emitWxCompanionAssets(this, bundle as WxBundle, context)
+            }
+        },
+
+        configureServer: {
+            order: 'post',
+            handler(server) {
+                developmentSession = new WxDevelopmentSession(context, server)
+                developmentSession.install()
+            }
+        },
+
+        closeBundle() {
+            return developmentSession?.close()
+        }
+    }
+}
+
+/** Supplies the complete WX target configuration from the same target owner as its plugin. */
+export function createWxViteConfig(context: BuildContext): UserConfig {
+    return {
+        define: createWxTaroDefines(),
+        experimental: context.development ? { bundledDev: true } : undefined,
+        css: {
+            lightningcss: {
+                visitor: {
+                    // keep CSS3 style single colon :before, :after
+                    // while WeChat Mini Program does not support the double colons versions
+                    Selector(selector) {
+                        return selector.map((component) => {
+                            if (
+                                component.type === 'pseudo-element' &&
+                                (component.kind === 'before' || component.kind === 'after')
+                            ) {
+                                return {
+                                    type: 'pseudo-element' as const,
+                                    kind: 'custom' as const,
+                                    name: component.kind
+                                }
+                            }
+                            return component
+                        })
+                    }
+                }
+            }
+        },
+        resolve: {
+            alias: [{ find: /^@tarojs\/components$/, replacement: taroWxComponentsPath }]
+        },
+        build: {
+            target: 'es2018',
+            assetsInlineLimit: 1024,
+            cssCodeSplit: false,
+            cssMinify: context.development ? false : 'lightningcss',
+            minify: !context.development,
+            rolldownOptions: {
+                input: { app: virtualWxAppId },
+                experimental: {
+                    // remove vite virtual module \0 in comments, which causes WeChat DevTools failed to compile
+                    attachDebugInfo: 'none'
+                },
+                output: {
+                    format: 'cjs',
+                    entryFileNames: '[name].js',
+                    assetFileNames: 'assets/[name][extname]',
+                    chunkFileNames: ({ name }) => `${name === 'rolldown-runtime' ? 'runtime' : name}.js`,
+                    strictExecutionOrder: true,
+                    codeSplitting: {
+                        includeDependenciesRecursively: false,
+                        minSize: 0,
+                        groups: [
+                            { name: 'taro', test: isWxTaroChunkModule, priority: 100 },
+                            { name: 'vendors', test: isNodeModule, priority: 10 },
+                            { name: 'common', minShareCount: 2, minModuleSize: 1, priority: 1 }
+                        ]
+                    }
+                }
+            }
+        }
+    }
+}
+
+function createWxTaroDefines(): Record<string, string> {
+    return {
+        'process.env.FRAMEWORK': JSON.stringify('react'),
+        'process.env.SUPPORT_TARO_POLYFILL': JSON.stringify('disabled'),
+        'process.env.TARO_ENV': JSON.stringify('weapp'),
+        'process.env.TARO_PLATFORM': JSON.stringify('mini'),
+        'process.env.TARO_VERSION': JSON.stringify(taroVersion),
+        ENABLE_ADJACENT_HTML: 'false',
+        ENABLE_CLONE_NODE: 'false',
+        ENABLE_CONTAINS: 'false',
+        ENABLE_INNER_HTML: 'false',
+        ENABLE_MUTATION_OBSERVER: 'false',
+        ENABLE_SIZE_APIS: 'false',
+        ENABLE_TEMPLATE_CONTENT: 'false'
+    }
+}
+
+function isWxTaroChunkModule(id: string): boolean {
+    const normalizedId = normalizeModuleId(id)
+    return normalizedId.includes('/node_modules/@tarojs/') || normalizedId.startsWith(`${vitePluginTaroSourcePath}/`)
+}
+
+function isNodeModule(id: string): boolean {
+    return normalizeModuleId(id).includes('/node_modules/')
+}

package/src/node/targets/wx/react-refresh.ts

@@ -0,0 +1,51 @@
+import { transformWithOxc } from 'vite'
+import { normalizeModuleId } from '../../utils/modules.ts'
+
+/** Rewrites Vite's browser-oriented Refresh output for the WX App Service global environment. */
+export async function transformWxReactRefreshModule(
+    code: string,
+    id: string,
+    appComponentFile: string
+): Promise<string> {
+    const appFile = normalizeModuleId(appComponentFile)
+    const instrumented = normalizeModuleId(id) === appFile ? await instrumentWxAppComponent(code, appFile) : code
+    return instrumented
+        .replaceAll('window.$Refresh', 'globalThis.$Refresh')
+        .replaceAll('window.__registerBeforePerformReactRefresh', 'globalThis.__registerBeforePerformReactRefresh')
+        .replaceAll('window.__getReactRefreshIgnoredExports', 'globalThis.__getReactRefreshIgnoredExports')
+        .replace(
+            'export function register(type, id) {',
+            'export function register(type, id) {\n  if (globalThis.__VITE_PLUGIN_TARO_WX_PAGE_UPDATE__?.blockRefreshRegistration) return'
+        )
+        .replace(
+            '\n  performReactRefresh()\n',
+            '\n  globalThis.__VITE_PLUGIN_TARO_WX_PAGE_UPDATE__?.afterRefresh?.(performReactRefresh())\n'
+        )
+}
+
+/** Creates the virtual preamble that installs React Refresh before the generated WX App entry executes. */
+export function createWxReactRefreshPreambleSource(): string {
+    return `import RefreshRuntime from '/@react-refresh'
+RefreshRuntime.injectIntoGlobalHook(globalThis)
+globalThis.$RefreshReg$ = () => {}
+globalThis.$RefreshSig$ = () => (type) => type
+`
+}
+
+/** Adds Refresh registration to JSX-free App modules that Vite's normal JSX transform would otherwise skip. */
+async function instrumentWxAppComponent(code: string, appFile: string): Promise<string> {
+    const transformed = await transformWithOxc(code, appFile, {
+        lang: 'js',
+        sourcemap: false,
+        jsx: { refresh: true }
+    })
+    return `import {
+    createSignatureFunctionForTransform as __wxCreateRefreshSignature,
+    register as __wxRegisterRefreshType
+} from '/@react-refresh'
+const $RefreshReg$ = (type, id) => __wxRegisterRefreshType(type, ${JSON.stringify(`${appFile} `)} + id)
+const $RefreshSig$ = __wxCreateRefreshSignature
+${transformed.code}
+if (import.meta.hot) import.meta.hot.accept()
+`
+}

package/src/node/targets/wx/virtual-modules.ts

@@ -0,0 +1,152 @@
+/**
+ * Defines the generated WX application graph.
+ *
+ * App, page, and component IDs become native entry chunks. The Refresh preamble is an App bootstrap module, while the
+ * page-preload ID deliberately becomes its own development file with a later, page-only execution phase.
+ */
+import type { VitePluginTaroPageOption } from '../../../options.ts'
+import type { BuildContext } from '../../build-context.ts'
+import { createPageComponentImportPath, toViteFileImportPath } from '../../utils/modules.ts'
+import { resolvePackageFile } from '../../utils/packages.ts'
+import { wxPagePreloadFile } from './development-files.ts'
+import { createWxReactRefreshPreambleSource } from './react-refresh.ts'
+
+const wxTaroRuntimeImportPath = runtimeImportPath('taro-runtime.js')
+const wxPageUpdateImportPath = runtimeImportPath('page-update.js')
+const wxUpdateClientImportPath = runtimeImportPath('update-client.js')
+
+/** Generated native App entry. */
+export const virtualWxAppId = 'virtual:vite-plugin-taro/wx/app'
+
+/** Generated recursive Taro component entry. */
+const virtualWxComponentId = 'virtual:vite-plugin-taro/wx/component'
+
+/** Prefix for one generated native entry per configured page route. */
+const virtualWxPageIdPrefix = 'virtual:vite-plugin-taro/wx/page/'
+
+/** App bootstrap module that installs React Refresh globals before application modules execute. */
+const virtualWxRefreshPreambleId = 'virtual:vite-plugin-taro/wx/refresh-preamble'
+
+/** Development-only entry that initializes all configured page components before update replay. */
+const virtualWxPagePreloadId = 'virtual:vite-plugin-taro/wx/page-preload'
+
+type WxChunkEmitter = {
+    emitFile(chunk: { type: 'chunk'; id: string; fileName: string; implicitlyLoadedAfterOneOf: string[] }): string
+}
+
+export function isWxVirtualModuleId(id: string): boolean {
+    return (
+        id === virtualWxAppId ||
+        id === virtualWxComponentId ||
+        id === virtualWxRefreshPreambleId ||
+        id === virtualWxPagePreloadId ||
+        id.startsWith(virtualWxPageIdPrefix)
+    )
+}
+
+export function loadWxVirtualModule(id: string, context: BuildContext): string | undefined {
+    if (id === virtualWxRefreshPreambleId) {
+        return createWxReactRefreshPreambleSource()
+    }
+    if (id === virtualWxAppId) {
+        return createWxAppEntrySource(context)
+    }
+    if (id === virtualWxComponentId) {
+        return createWxComponentEntrySource()
+    }
+    if (id === virtualWxPagePreloadId) {
+        return createWxPagePreloadSource(context)
+    }
+
+    if (id.startsWith(virtualWxPageIdPrefix)) {
+        const pagePath = id.slice(virtualWxPageIdPrefix.length)
+
+        const page = context.project.pages.find((candidate) => candidate.path === pagePath)
+        if (page) {
+            return createWxPageEntrySource(page, context)
+        }
+    }
+}
+
+/** Registers every configured page and the shared recursive component as eager WX entry chunks. */
+export function emitWxEntryChunks(emitter: WxChunkEmitter, context: BuildContext, id: string): void {
+    if (id !== virtualWxAppId) return
+
+    for (const page of context.project.pages) {
+        emitter.emitFile({
+            type: 'chunk',
+            id: `${virtualWxPageIdPrefix}${page.path}`,
+            fileName: `${page.path}.js`,
+            implicitlyLoadedAfterOneOf: [id]
+        })
+    }
+
+    emitter.emitFile({
+        type: 'chunk',
+        id: virtualWxComponentId,
+        fileName: 'comp.js',
+        implicitlyLoadedAfterOneOf: [id]
+    })
+
+    if (context.development) {
+        emitter.emitFile({
+            type: 'chunk',
+            id: virtualWxPagePreloadId,
+            fileName: wxPagePreloadFile,
+            implicitlyLoadedAfterOneOf: [id]
+        })
+    }
+}
+
+function createWxAppEntrySource(context: BuildContext): string {
+    const refreshPreamble = context.development ? `import ${JSON.stringify(virtualWxRefreshPreambleId)}\n` : ''
+    const updateClient = context.development
+        ? `import { startWxUpdateClient } from ${JSON.stringify(wxUpdateClientImportPath)}\n`
+        : ''
+    return `${refreshPreamble}${updateClient}import { createReactApp, ReactDOM } from ${JSON.stringify(wxTaroRuntimeImportPath)}
+import React from 'react'
+import AppComponent from ${JSON.stringify(toViteFileImportPath(context.project.appComponentFile))}
+
+const appConfig = ${JSON.stringify(context.project.appConfig)}
+App(createReactApp(AppComponent, React, ReactDOM, appConfig))
+${context.development ? 'startWxUpdateClient()' : ''}
+`
+}
+
+function createWxPageEntrySource(page: VitePluginTaroPageOption, context: BuildContext): string {
+    const hotUpdateImport = context.development
+        ? `import { decorateWxPageConfig, registerWxPage } from ${JSON.stringify(wxPageUpdateImportPath)}\n`
+        : ''
+    const createConfig = `createPageConfig(PageComponent, '${page.path}', { root: { cn: [] } }, pageConfig)`
+    const pageRegistration = context.development
+        ? `registerWxPage(${JSON.stringify(page.path)}, () => Page(taroPageConfig))`
+        : 'Page(taroPageConfig)'
+    return `${hotUpdateImport}import { createPageConfig } from ${JSON.stringify(wxTaroRuntimeImportPath)}
+import PageComponent from ${JSON.stringify(createPageComponentImportPath(page.path))}
+
+const pageConfig = ${JSON.stringify(page.config)}
+const taroPageConfig = ${context.development ? `decorateWxPageConfig(${createConfig})` : createConfig}
+if (PageComponent && PageComponent.behaviors) {
+  taroPageConfig.behaviors = (taroPageConfig.behaviors || []).concat(PageComponent.behaviors)
+}
+${pageRegistration}
+`
+}
+
+function createWxPagePreloadSource(context: BuildContext): string {
+    const imports = context.project.pages.map((page, index) => {
+        return `import Page${index} from ${JSON.stringify(createPageComponentImportPath(page.path))}`
+    })
+    return `${imports.join('\n')}\nvoid [${context.project.pages.map((_, index) => `Page${index}`).join(', ')}]\n`
+}
+
+function runtimeImportPath(fileName: string): string {
+    return toViteFileImportPath(resolvePackageFile('dist/runtime/wx', fileName))
+}
+
+function createWxComponentEntrySource(): string {
+    return `import { createRecursiveComponentConfig } from ${JSON.stringify(wxTaroRuntimeImportPath)}
+
+Component(createRecursiveComponentConfig())
+`
+}

package/src/node/utils/async.ts

@@ -0,0 +1,19 @@
+/** Generic asynchronous coordination helpers for Node-side plugin services. */
+export class SerializedTaskQueue {
+    private readonly reportError: (error: unknown) => void
+    private tail = Promise.resolve()
+
+    constructor(reportError: (error: unknown) => void) {
+        this.reportError = reportError
+    }
+
+    enqueue(task: () => Promise<void>): Promise<void> {
+        const work = this.tail.then(task)
+        this.tail = work.catch(this.reportError)
+        return work
+    }
+
+    async waitForIdle(): Promise<void> {
+        await this.tail
+    }
+}

package/src/node/utils/filesystem.ts

@@ -0,0 +1,45 @@
+/** Node-only filesystem helpers shared by build targets and development services. */
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+type FileSource = string | Uint8Array
+type FileWrite = { file: string; source: FileSource }
+
+/** Writes through a sibling temporary file so observers never read partial contents. */
+export async function writeFileAtomically(file: string, source: FileSource): Promise<void> {
+    await fs.mkdir(path.dirname(file), { recursive: true })
+    const temporaryFile = `${file}.tmp`
+    await fs.writeFile(temporaryFile, source)
+    await fs.rename(temporaryFile, file)
+}
+
+export async function writeFilesAtomically(files: FileWrite[]): Promise<void> {
+    await Promise.all(files.map(({ file, source }) => writeFileAtomically(file, source)))
+}
+
+/** Copies a directory when present and treats a missing optional source as empty. */
+export async function copyDirectoryIfExists(source: string, destination: string): Promise<void> {
+    if (!source) return
+    try {
+        await fs.cp(source, destination, { recursive: true, force: true })
+    } catch (error) {
+        if (!isMissingFileError(error)) throw error
+    }
+}
+
+/** Mirrors one optional file: copy existing files, ignore directories, and remove a missing source's destination. */
+export async function copyFileOrRemove(source: string, destination: string): Promise<void> {
+    try {
+        const stat = await fs.stat(source)
+        if (stat.isDirectory()) return
+        await fs.mkdir(path.dirname(destination), { recursive: true })
+        await fs.copyFile(source, destination)
+    } catch (error) {
+        if (!isMissingFileError(error)) throw error
+        await fs.rm(destination, { recursive: true, force: true })
+    }
+}
+
+function isMissingFileError(error: unknown): error is NodeJS.ErrnoException {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT'
+}

package/src/{vite/utils.ts → node/utils/modules.ts}

@@ -1,3 +1,4 @@
+/** Node-side helpers for application module files, Vite import specifiers, and normalized module IDs. */
 import path from 'node:path'
 
 /**
@@ -7,8 +8,15 @@ import path from 'node:path'
  * 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 createPageComponentImport(pagePath: string): string {
-    return toImportPath(`src/${pagePath}.tsx`)
+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`)
 }
 
 /**
@@ -17,7 +25,7 @@ export function createPageComponentImport(pagePath: string): string {
  * Rolldown does not reliably resolve raw Windows absolute paths from virtual
  * module source, so generated imports use Vite's /@fs/ prefix instead.
  */
-export function toImportPath(filePath: string): string {
+export function toViteFileImportPath(filePath: string): string {
     return `/@fs/${normalizeModuleId(path.resolve(filePath))}`
 }
 

package/src/node/utils/packages.ts

@@ -0,0 +1,10 @@
+/** 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'
+
+export const packageRequire = createRequire(import.meta.url)
+const packageRoot = path.dirname(packageRequire.resolve('vite-plugin-taro/package.json'))
+
+export function resolvePackageFile(...segments: string[]): string {
+    return path.join(packageRoot, ...segments)
+}

package/src/node/vite-plugin.ts

@@ -0,0 +1,41 @@
+import react from '@vitejs/plugin-react'
+import type { Plugin, 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'
+
+/** Creates the Vite plugins for the selected Taro target. */
+export default function vitePluginTaro(options: VitePluginTaroOptions): PluginOption[] {
+    const context = new BuildContext(options)
+    const targetPlugins =
+        context.project.target === 'wx' ? createWxTargetPlugins(context) : createH5TargetPlugins(context)
+
+    return [
+        createBuildCoordinator(context),
+        createConditionalDirectivePlugin(context),
+        createTaroRuntimePlugin(),
+        context.css.plugin,
+        ...react(),
+        ...targetPlugins
+    ]
+}
+
+/** 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

@@ -0,0 +1,25 @@
+/** Plain JSON object emitted into Mini Program/Web config payloads. */
+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. */
+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. */
+export interface VitePluginTaroOptions {
+    target: VitePluginTaroTarget
+    app: string
+    pages: VitePluginTaroPageOption[]
+    appJson: JsonObject
+    projectConfigJson: JsonObject
+    projectPrivateConfigJson: JsonObject
+    sitemapJson: JsonObject
+}

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

@@ -0,0 +1,3 @@
+/** Package-owned Taro CSS side effects imported by the H5 runtime entry. */
+declare module '@tarojs/components/global.css'
+declare module '@tarojs/components/dist/taro-components/taro-components.css'

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

@@ -0,0 +1,10 @@
+/** Runtime exports consumed by the generated H5 entry. */
+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 { window } from '@tarojs/runtime'

package/src/{virtual → runtime/taro}/api.ts

@@ -1,3 +1,6 @@
+/** Physical runtime module backing the public `virtual:taro/api` facade. */
+// Ensure Taro's React runtime registers its `initNativeApi` hook before @tarojs/taro is initialized.
+import '@tarojs/plugin-framework-react/dist/runtime'
 import { hooks } from '@tarojs/runtime'
 import Taro from '@tarojs/taro'
 

package/src/runtime/taro/components.ts

@@ -0,0 +1,2 @@
+/** Physical runtime module backing the public `virtual:taro/components` facade. */
+export * from '@tarojs/components'