vite-plugin-taro 0.3.2 → 0.4.0

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

@@ -0,0 +1,265 @@
+import path from 'node:path'
+import type { ExistingRawSourceMap } from 'rolldown'
+import { RolldownMagicString } from 'rolldown'
+import { parseAst } from 'rolldown/parseAst'
+import type { ESTree } from 'rolldown/utils'
+import { normalizeModuleId } from '../../../utils/modules.ts'
+import { clientTaroNativeId } from '../../client/constant.ts'
+
+export type NativeComponentDefinition = {
+    folder: string
+    entry: string
+    fields: readonly string[]
+}
+
+type NativeComponentMacroImport = {
+    declaration: ESTree.ImportDeclaration
+    names: readonly string[]
+}
+
+/** Replaces native component interface calls with source-folder names and returns their static metadata. */
+export function transformNativeComponentInterfaces(code: string, id: string, sourcemap: boolean) {
+    const moduleId = normalizeModuleId(id)
+    const program = parseAst(
+        code,
+        {
+            astType: 'ts',
+            lang: 'tsx',
+            preserveParens: false,
+            sourceType: 'module'
+        },
+        moduleId
+    )
+    const declaredInterfaces = collectInterfaceDeclarations(program)
+    const macroImports = collectMacroImports(program)
+    const importedMacroNames: ReadonlySet<string> = new Set(macroImports.flatMap((item) => item.names))
+    const calls = collectTopLevelMacroCalls(program, importedMacroNames)
+    const replacements = calls.map((call) => {
+        const definition = parseDefinition(call, moduleId, declaredInterfaces, (message) =>
+            createTransformError(message, moduleId, code, call.start)
+        )
+        return { call, definition }
+    })
+
+    // This transform-local mutable buffer applies non-overlapping AST edits without regenerating untouched source.
+    const transformed = new RolldownMagicString(code, { filename: moduleId })
+    replacements.forEach(({ call, definition }) => {
+        transformed.overwrite(call.start, call.end, JSON.stringify(path.posix.basename(definition.folder)))
+    })
+    macroImports.forEach(({ declaration }) => {
+        transformed.remove(declaration.start, declaration.end)
+    })
+
+    return {
+        code: transformed.toString(),
+        map: sourcemap ? createSourceMap(transformed, moduleId) : null,
+        definitions: replacements.map(({ definition }) => definition)
+    }
+}
+
+/** Normalizes Rolldown's native source-map object to the public plugin source-map shape. */
+function createSourceMap(transformed: RolldownMagicString, moduleId: string): ExistingRawSourceMap {
+    const sourceMap = transformed.generateMap({
+        hires: 'boundary',
+        includeContent: true,
+        source: moduleId
+    })
+    return {
+        file: sourceMap.file,
+        mappings: sourceMap.mappings,
+        names: sourceMap.names,
+        sources: sourceMap.sources,
+        sourcesContent: sourceMap.sourcesContent,
+        version: sourceMap.version
+    }
+}
+
+/** Finds named imports of the compile-time macro and records their local aliases. */
+function collectMacroImports(program: ESTree.Program): NativeComponentMacroImport[] {
+    return program.body.flatMap((statement) => {
+        if (statement.type !== 'ImportDeclaration' || statement.source.value !== clientTaroNativeId) {
+            return []
+        }
+        const names = statement.specifiers.flatMap((specifier) => {
+            if (specifier.type !== 'ImportSpecifier' || getStaticName(specifier.imported) !== 'defineNativeComponent') {
+                return []
+            }
+            return [specifier.local.name]
+        })
+        return names.length === 0 ? [] : [{ declaration: statement, names }]
+    })
+}
+
+/** Collects direct module-level macro calls, excluding calls inside nested scopes. */
+function collectTopLevelMacroCalls(
+    program: ESTree.Program,
+    importedMacroNames: ReadonlySet<string>
+): ESTree.CallExpression[] {
+    return program.body.flatMap((statement) => {
+        if (statement.type === 'ExpressionStatement') {
+            return isImportedMacroCall(statement.expression, importedMacroNames) ? [statement.expression] : []
+        }
+        if (statement.type === 'ExportDefaultDeclaration') {
+            return isImportedMacroCall(statement.declaration, importedMacroNames) ? [statement.declaration] : []
+        }
+
+        const declaration = statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement
+        if (declaration?.type !== 'VariableDeclaration') {
+            return []
+        }
+        return declaration.declarations.flatMap(({ init }) => {
+            return isImportedMacroCall(init, importedMacroNames) ? [init] : []
+        })
+    })
+}
+
+/** Matches a direct call to one of the macro's module-level import bindings. */
+function isImportedMacroCall(
+    node: ESTree.Expression | ESTree.Declaration | null | undefined,
+    importedMacroNames: ReadonlySet<string>
+): node is ESTree.CallExpression {
+    return (
+        node?.type === 'CallExpression' && node.callee.type === 'Identifier' && importedMacroNames.has(node.callee.name)
+    )
+}
+
+/** Parses one native entry loader and its optional TypeScript interface. */
+function parseDefinition(
+    call: ESTree.CallExpression,
+    moduleId: string,
+    declaredInterfaces: ReadonlyMap<string, readonly ESTree.TSSignature[]>,
+    buildError: (message: string) => Error
+): NativeComponentDefinition {
+    if (call.arguments.length !== 1) {
+        throw buildError('defineNativeComponent() requires exactly one entry loader')
+    }
+    const entryReference = readStaticEntryImport(call.arguments[0])
+    if (!entryReference) {
+        throw buildError('Native component entry must use () => import(...) with a static relative .js path')
+    }
+
+    const entryPath = normalizeModuleId(path.resolve(path.dirname(moduleId), entryReference))
+    return {
+        folder: path.posix.dirname(entryPath),
+        entry: path.posix.basename(entryPath, '.js'),
+        fields: readInterfaceFields(call.typeArguments, declaredInterfaces, buildError)
+    }
+}
+
+/** Collects non-generic local object aliases and interfaces as native template field declarations. */
+function collectInterfaceDeclarations(program: ESTree.Program): ReadonlyMap<string, readonly ESTree.TSSignature[]> {
+    // This module-local map supports nearby declarations without constructing a TypeScript type-checker program.
+    const declarations = new Map<string, readonly ESTree.TSSignature[]>()
+    for (const statement of program.body) {
+        const declaration = statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement
+        if (
+            declaration?.type === 'TSTypeAliasDeclaration' &&
+            !declaration.typeParameters &&
+            declaration.typeAnnotation.type === 'TSTypeLiteral'
+        ) {
+            declarations.set(declaration.id.name, declaration.typeAnnotation.members)
+            continue
+        }
+        if (
+            declaration?.type === 'TSInterfaceDeclaration' &&
+            !declaration.typeParameters &&
+            declaration.extends.length === 0
+        ) {
+            declarations.set(declaration.id.name, declaration.body.body)
+        }
+    }
+    return declarations
+}
+
+/** Resolves an inline type or a non-generic object declaration from the current module. */
+function resolveInterfaceMembers(
+    typeNode: ESTree.TSType,
+    declarations: ReadonlyMap<string, readonly ESTree.TSSignature[]>
+): readonly ESTree.TSSignature[] | undefined {
+    if (typeNode.type === 'TSTypeLiteral') {
+        return typeNode.members
+    }
+    if (typeNode.type === 'TSTypeReference' && typeNode.typeName.type === 'Identifier' && !typeNode.typeArguments) {
+        return declarations.get(typeNode.typeName.name)
+    }
+}
+
+/** Reads native template field names without resolving or validating their TypeScript value types. */
+function readInterfaceFields(
+    typeArguments: ESTree.TSTypeParameterInstantiation | null | undefined,
+    declaredInterfaces: ReadonlyMap<string, readonly ESTree.TSSignature[]>,
+    buildError: (message: string) => Error
+): string[] {
+    if (!typeArguments) {
+        return []
+    }
+    if (typeArguments.params.length !== 1) {
+        throw buildError('Native component interface must be one TypeScript object type')
+    }
+    const firstType = typeArguments.params[0]
+    const members = firstType ? resolveInterfaceMembers(firstType, declaredInterfaces) : undefined
+    if (!members) {
+        throw buildError('Native component interface must be inline or declared in the same module')
+    }
+
+    // This local set preserves declaration order while rejecting ambiguous duplicate template fields.
+    const names = new Set<string>()
+    for (const member of members) {
+        if (member.type !== 'TSPropertySignature' && member.type !== 'TSMethodSignature') {
+            throw buildError('Native component interface must contain only static fields')
+        }
+        if (member.computed) {
+            throw buildError('Native component interface contains a computed field')
+        }
+        const name = getStaticName(member.key)
+        if (!name) {
+            throw buildError('Native component interface contains a computed field')
+        }
+        if (names.has(name)) {
+            throw buildError(`Duplicate native component interface field: ${name}`)
+        }
+        names.add(name)
+    }
+
+    return [...names].filter((name) => name !== 'children')
+}
+
+/** Reads an identifier or string-literal key. */
+function getStaticName(node: ESTree.Node): string | undefined {
+    if (node.type === 'Identifier') {
+        return node.name
+    }
+    if (node.type === 'Literal' && typeof node.value === 'string') {
+        return node.value
+    }
+}
+
+/** Reads a zero-argument entry loader containing one statically resolvable native `.js` import. */
+function readStaticEntryImport(node: ESTree.Argument | null | undefined): string | undefined {
+    if (node?.type !== 'ArrowFunctionExpression' || node.params.length !== 0 || node.body.type !== 'ImportExpression') {
+        return undefined
+    }
+    const importExpression = node.body
+    if (
+        importExpression.source.type !== 'Literal' ||
+        typeof importExpression.source.value !== 'string' ||
+        importExpression.options !== null ||
+        !isLocalJavaScriptEntry(importExpression.source.value)
+    ) {
+        return undefined
+    }
+    return importExpression.source.value
+}
+
+/** Limits component entries to JavaScript files reachable from their interface module. */
+function isLocalJavaScriptEntry(entry: string): boolean {
+    return (entry.startsWith('./') || entry.startsWith('../')) && path.posix.extname(entry) === '.js'
+}
+
+/** Adds a stable source location to semantic errors reported after parsing. */
+function createTransformError(message: string, moduleId: string, code: string, offset: number): Error {
+    const prefix = code.slice(0, offset)
+    const line = prefix.split('\n').length
+    const column = offset - prefix.lastIndexOf('\n')
+    return new Error(`${message}\n${moduleId}:${line}:${column}`)
+}

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

@@ -0,0 +1,27 @@
+import type { Rolldown } from 'vite'
+import type { VitePluginTaroOptions } from '../../../../options.ts'
+import { createNativeComponentOutput } from '../native/create-native-component-output.ts'
+import type { GeneratedSubpackage } from '../placement/placer.ts'
+import { createJsonAssets } from './json.ts'
+import { createTemplateAssets } from './templates.ts'
+
+/** Creates every native companion file derived from the final Rolldown bundle. */
+export async function createOutputFiles({
+    bundle,
+    options,
+    subpackages,
+    getModuleInfo
+}: {
+    bundle: Rolldown.OutputBundle
+    options: VitePluginTaroOptions
+    subpackages: readonly GeneratedSubpackage[]
+    getModuleInfo: (moduleId: string) => { meta: Rolldown.CustomPluginOptions } | null
+}): Promise<Rolldown.EmittedFile[]> {
+    const nativeOutput = await createNativeComponentOutput({ bundle, getModuleInfo })
+
+    return [
+        ...createJsonAssets({ options, subpackages, nativeComponents: nativeOutput.registrations }),
+        ...createTemplateAssets(bundle, options, nativeOutput.registrations),
+        ...nativeOutput.files
+    ]
+}

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

@@ -0,0 +1,79 @@
+import type { Rolldown } from 'vite'
+import type { JsonObject, VitePluginTaroOptions, VitePluginTaroPageOption } from '../../../../options.ts'
+import { createAppConfig } from '../../../utils/project-config.ts'
+import type { GeneratedSubpackage } from '../placement/placer.ts'
+import { isGeneratedSubpackageFile } from '../placement/plan.ts'
+import { toRootRelativePath } from './relative-root.ts'
+
+/** Creates every configured native JSON asset. */
+export function createJsonAssets({
+    options,
+    subpackages,
+    nativeComponents
+}: {
+    options: VitePluginTaroOptions
+    subpackages: readonly GeneratedSubpackage[]
+    nativeComponents: readonly { name: string; componentPath: string }[]
+}): Rolldown.EmittedAsset[] {
+    return [
+        createJsonAsset('app.json', {
+            ...createAppConfig(options),
+            ...(subpackages.length > 0 ? { subPackages: subpackages } : {})
+        }),
+
+        ...options.pages.map((page) => createJsonAsset(`${page.path}.json`, createPageJson(page, nativeComponents))),
+
+        createJsonAsset('project.config.json', options.projectConfigJson),
+
+        ...(options.projectPrivateConfigJson
+            ? [createJsonAsset('project.private.config.json', options.projectPrivateConfigJson)]
+            : []),
+
+        createJsonAsset('sitemap.json', options.sitemapJson)
+    ]
+}
+
+/** Creates Page JSON with generated Taro and native component registrations. */
+function createPageJson(
+    page: VitePluginTaroPageOption,
+    nativeComponents: readonly { name: string; componentPath: string }[]
+): JsonObject {
+    const usingComponents = isJsonObject(page.config.usingComponents) ? page.config.usingComponents : {}
+
+    // Cross-package components require a placeholder while WeChat downloads their generated subpackage. Paths are
+    // root-absolute, so remove the leading slash before testing the output-relative subpackage prefix.
+    // https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/async.html
+    // https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/placeholder.html
+    const placeholderEntries = nativeComponents.flatMap(({ name, componentPath }) =>
+        isGeneratedSubpackageFile(componentPath.slice(1)) ? ([[name, 'view']] as const) : []
+    )
+
+    return {
+        ...page.config,
+        ...(placeholderEntries.length > 0 ? { componentPlaceholder: Object.fromEntries(placeholderEntries) } : {}),
+        usingComponents: {
+            ...usingComponents,
+            ...Object.fromEntries(nativeComponents.map(({ name, componentPath }) => [name, componentPath])),
+            comp: toRootRelativePath(page.path, 'comp')
+        }
+    }
+}
+
+/** Tests whether a configured JSON value can be merged as an object. */
+function isJsonObject(value: unknown): value is JsonObject {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Serializes one native JSON object with stable formatting. */
+export function renderJson(value: JsonObject): string {
+    return `${JSON.stringify(value, null, 4)}\n`
+}
+
+/** Creates one native JSON asset. */
+function createJsonAsset(fileName: string, value: JsonObject): Rolldown.EmittedAsset {
+    return {
+        type: 'asset',
+        fileName,
+        source: renderJson(value)
+    }
+}

package/src/node/plugins/wx/output/relative-root.ts

@@ -0,0 +1,7 @@
+import path from 'node:path'
+
+/** Creates a Page-relative path to a file emitted at the wx output root. */
+export function toRootRelativePath(pagePath: string, rootFileName: string): string {
+    const relativePath = path.posix.relative(path.posix.dirname(pagePath), rootFileName)
+    return relativePath.startsWith('.') ? relativePath : `./${relativePath}`
+}

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

@@ -0,0 +1,141 @@
+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 { normalizeModuleId } from '../../../utils/modules.ts'
+import { packageRequire } from '../../../utils/packages.ts'
+import { renderJson } from './json.ts'
+import { toRootRelativePath } from './relative-root.ts'
+
+type TemplateComponentConfig = {
+    includes: Set<string>
+    exclude: Set<string>
+    thirdPartyComponents: Map<string, Set<string>>
+    includeAll: boolean
+}
+
+const taroComponentsModulePath = packageRequire.resolve('@tarojs/plugin-platform-weapp/dist/components-react')
+
+/** Creates Taro's shared WeChat templates and native WXML/WXSS companions for every Page. */
+export function createTemplateAssets(
+    bundle: Rolldown.OutputBundle,
+    options: VitePluginTaroOptions,
+    nativeComponents: readonly {
+        name: string
+        fields: readonly string[]
+    }[]
+): Rolldown.EmittedAsset[] {
+    const templateBuilder = createTemplateBuilder()
+
+    return [
+        createAsset(
+            'base.wxml',
+            templateBuilder.buildTemplate(collectTemplateComponentConfig(bundle, nativeComponents))
+        ),
+        createAsset('utils.wxs', templateBuilder.buildXScript()),
+        createAsset('comp.wxml', templateBuilder.buildBaseComponentTemplate('.wxml')),
+        createAsset('comp.json', renderJson(createComponentJson())),
+        ...options.pages.flatMap((page) => [
+            createAsset(
+                `${page.path}.wxml`,
+                templateBuilder.buildPageTemplate(toRootRelativePath(page.path, 'base.wxml'), {
+                    content: page.config,
+                    path: page.path
+                })
+            ),
+            createAsset(`${page.path}.wxss`, '')
+        ])
+    ]
+}
+
+/** Creates the Taro WeChat template builder without invoking its Webpack integration. */
+function createTemplateBuilder() {
+    const platform = new WxPlatform(
+        {
+            helper: {
+                recursiveMerge
+            },
+            modifyWebpackChain() {},
+            registerPlatform() {}
+        },
+        {},
+        {}
+    )
+    platform.modifyTemplate({})
+    return platform.template
+}
+
+/** Creates template metadata from reachable Taro hosts and native component JSX fields. */
+function collectTemplateComponentConfig(
+    bundle: Rolldown.OutputBundle,
+    nativeComponents: readonly {
+        name: string
+        fields: readonly string[]
+    }[]
+): TemplateComponentConfig {
+    // This local config accumulates names in output order before the template builder consumes it.
+    const config: TemplateComponentConfig = {
+        includes: new Set([
+            'view',
+            'catch-view',
+            'static-view',
+            'pure-view',
+            'click-view',
+            'scroll-view',
+            'image',
+            'static-image',
+            'text',
+            'static-text'
+        ]),
+        exclude: new Set(),
+        thirdPartyComponents: new Map(),
+        includeAll: false
+    }
+    const components = findBundleModule(bundle, taroComponentsModulePath)
+    for (const name of components?.renderedExports ?? []) {
+        config.includes.add(toDashed(name))
+    }
+    for (const component of nativeComponents) {
+        config.thirdPartyComponents.set(component.name, new Set(component.fields))
+    }
+    return config
+}
+
+/** Finds one module in the final chunk metadata. */
+function findBundleModule(bundle: Rolldown.OutputBundle, resolvedId: string): Rolldown.RenderedModule | undefined {
+    const normalizedResolvedId = normalizeModuleId(resolvedId)
+    for (const output of Object.values(bundle)) {
+        if (output.type !== 'chunk') {
+            continue
+        }
+        const found = Object.entries(output.modules).find(([id]) => normalizeModuleId(id) === normalizedResolvedId)
+        if (found) {
+            return found[1]
+        }
+    }
+}
+
+/** Converts a React component export to Taro's dashed host-component name. */
+function toDashed(value: string): string {
+    return value.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
+}
+
+/** Creates the recursive component configuration expected by Taro's templates. */
+function createComponentJson(): JsonObject {
+    return {
+        component: true,
+        styleIsolation: 'apply-shared',
+        usingComponents: {
+            comp: './comp'
+        }
+    }
+}
+
+/** Creates one emitted template or style asset. */
+function createAsset(fileName: string, source: string): Rolldown.EmittedAsset {
+    return {
+        type: 'asset',
+        fileName,
+        source
+    }
+}