vite-plugin-taro 0.3.0 → 0.3.2

package/dist/node/build-context.d.ts

@@ -7,7 +7,7 @@ type ProjectContext = Readonly<{
     pages: readonly VitePluginTaroPageOption[];
     appConfig: JsonObject;
     projectConfigJson: JsonObject;
-    projectPrivateConfigJson: JsonObject;
+    projectPrivateConfigJson?: JsonObject;
     sitemapJson: JsonObject;
 }>;
 /** Owns the shared project, Vite lifecycle state, and cross-target services for one build. */

package/dist/node/build-context.js

@@ -7,6 +7,7 @@ export class BuildContext {
     developmentMode;
     resolvedViteConfig;
     constructor(options) {
+        this.css = new CssPipeline(options.target);
         this.project = {
             target: options.target,
             appComponentFile: path.resolve(options.app),
@@ -19,7 +20,6 @@ export class BuildContext {
             projectPrivateConfigJson: options.projectPrivateConfigJson,
             sitemapJson: options.sitemapJson
         };
-        this.css = new CssPipeline(options.target);
     }
     configure(environment) {
         if (this.developmentMode !== undefined)
@@ -33,7 +33,6 @@ export class BuildContext {
         if (this.resolvedViteConfig)
             throw new Error('vite-plugin-taro build context was already resolved.');
         this.resolvedViteConfig = config;
-        this.css.resolve(config.root);
     }
     get development() {
         if (this.developmentMode === undefined)

package/dist/node/css/css-pipeline.d.ts

@@ -1,21 +1,35 @@
-import type { Plugin } from 'vite';
+import type { PluginOption } from 'vite';
 import type { VitePluginTaroTarget } from '../../options.ts';
-type CssTransformResult = {
+type PatchResult = {
     code: string;
-    map: null;
+} | {
+    requiresFullBuild: true;
 };
-/** Owns CSS generation and the class-name state shared by normal chunks and literal WX patches. */
+/** Owns Tailwind's Vite integration and native WX patch synchronization. */
 export declare class CssPipeline {
-    readonly plugin: Plugin;
-    private readonly target;
-    private readonly runtimeClassSet;
-    private projectRoot;
+    readonly plugins: PluginOption[];
+    private readonly entries;
+    private readonly sourceCache;
     private wxContext;
+    private root;
+    private builtClassSet;
+    /** Composes the upstream web/WX plugins and adds candidate tracking only for native WX patches. */
     constructor(target: VitePluginTaroTarget);
-    resolve(projectRoot: string): void;
-    transformWxClassNames(code: string, filename: string): Promise<CssTransformResult>;
-    private createPlugin;
-    private getProjectRoot;
+    /** Records every utility guaranteed to exist after a successful full WX build. */
+    captureFullBuild(): Promise<void>;
+    /** Applies upstream mini-program compatibility transforms to Taro's fully materialized WXSS. */
+    transformWxss(code: string): Promise<string>;
+    /** Escapes a JavaScript-only WX patch, or rejects it when its utilities require new WXSS. */
+    transformNativePatch(code: string, filename: string, files: string[]): Promise<PatchResult>;
+    /** Retains Vite's root for resolving later CSS transforms and changed-file notifications. */
+    private resolveWx;
+    /** Creates one validator per Tailwind entry and refreshes the shared upstream WX transformer. */
+    private registerCssEntry;
+    /** Incrementally checks changed source files for utilities absent from the completed WX build. */
+    private hasAddedCandidates;
+    /** Returns the initialized WX transformer and detects invalid lifecycle ordering. */
     private getWxContext;
+    /** Returns the resolved project root and detects use before Vite configuration. */
+    private getRoot;
 }
 export {};

package/dist/node/css/css-pipeline.js

@@ -1,129 +1,154 @@
+import fs from 'node:fs/promises';
 import path from 'node:path';
+import { extractSourceCandidates } from '@tailwindcss-mangle/engine';
 import { createContext } from 'weapp-tailwindcss/core';
 import { createWeappTailwindcssGenerator, resolveTailwindV4Source } from 'weapp-tailwindcss/generator';
+import { WeappTailwindcss } from 'weapp-tailwindcss/vite';
 import { normalizeModuleId } from '../utils/modules.js';
+import { resolvePackageFile } from '../utils/packages.js';
 const wxStyleOptions = {
     cssCalc: false,
     autoprefixer: false,
     rem2rpx: true,
     px2rpx: true
 };
-/** Owns CSS generation and the class-name state shared by normal chunks and literal WX patches. */
+/** Owns Tailwind's Vite integration and native WX patch synchronization. */
 export class CssPipeline {
-    plugin;
-    target;
-    runtimeClassSet = new Set();
-    projectRoot;
+    plugins;
+    // Each Tailwind CSS entry can define a different design system, so additions must pass every relevant validator.
+    entries = new Map();
+    // Vite can report the same source more than once; avoid repeating extraction and validation.
+    sourceCache = new Map();
+    // Upstream owns WX JavaScript escaping; this context is deliberately reused between patches.
     wxContext;
+    // CSS transforms arrive after configResolved, so the Vite root is retained for source and module resolution.
+    root;
+    // Only classes represented by a completed WX build are safe to publish in a JavaScript-only patch.
+    builtClassSet = new Set();
+    /** Composes the upstream web/WX plugins and adds candidate tracking only for native WX patches. */
     constructor(target) {
-        this.target = target;
-        this.plugin = this.createPlugin();
+        const pipeline = this;
+        const wx = target === 'wx';
+        this.plugins = [
+            wx
+                ? {
+                    name: 'vite-plugin-taro:wx-tailwind-pipeline',
+                    enforce: 'pre',
+                    configResolved(config) {
+                        pipeline.resolveWx(config);
+                    },
+                    async transform(code, id) {
+                        if (!isTailwindCssEntry(code, id))
+                            return;
+                        await pipeline.registerCssEntry(id, code);
+                    }
+                }
+                : undefined,
+            ...(WeappTailwindcss({
+                appType: 'taro',
+                // Route split Tailwind imports around Vite's unresolved production CSS package imports.
+                rewriteCssImports: true,
+                generator: { target: wx ? 'weapp' : 'web' },
+                ...(wx ? wxStyleOptions : {}),
+                logLevel: 'silent'
+            }) ?? [])
+        ];
     }
-    resolve(projectRoot) {
-        if (this.projectRoot)
-            throw new Error('vite-plugin-taro CSS pipeline was already resolved.');
-        this.projectRoot = projectRoot;
-        this.wxContext = this.target === 'wx' ? createWxCssContext(projectRoot) : undefined;
+    /** Records every utility guaranteed to exist after a successful full WX build. */
+    async captureFullBuild() {
+        this.sourceCache.clear();
+        // Preserve removed development CSS, matching upstream's append-only HMR default.
+        for (const { generator } of this.entries.values()) {
+            const result = await generator.generate({ scanSources: true });
+            for (const candidate of result.classSet)
+                this.builtClassSet.add(candidate);
+        }
     }
-    async transformWxClassNames(code, filename) {
-        if (!this.wxContext || this.runtimeClassSet.size === 0)
-            return { code, map: null };
-        const result = await this.wxContext.transformJs(code, {
-            runtimeSet: this.runtimeClassSet,
+    /** Applies upstream mini-program compatibility transforms to Taro's fully materialized WXSS. */
+    async transformWxss(code) {
+        return (await this.getWxContext().transformWxss(code)).css;
+    }
+    /** Escapes a JavaScript-only WX patch, or rejects it when its utilities require new WXSS. */
+    async transformNativePatch(code, filename, files) {
+        if (await this.hasAddedCandidates(files))
+            return { requiresFullBuild: true };
+        const result = await this.getWxContext().transformJs(code, {
+            runtimeSet: this.builtClassSet,
             filename,
             generateMap: false
         });
-        return { code: result.code, map: null };
+        return { code: result.code };
     }
-    createPlugin() {
-        const pipeline = this;
-        return {
-            name: 'vite-plugin-taro:css',
-            enforce: 'pre',
-            buildStart() {
-                pipeline.runtimeClassSet.clear();
-            },
-            async transform(code, id) {
-                if (!isCssModuleId(id) || !shouldGenerateTailwindCss(code))
-                    return;
-                const projectRoot = pipeline.getProjectRoot();
-                const cssFile = resolveCssFile(id, projectRoot);
-                const cssBase = path.dirname(cssFile);
-                const source = await resolveTailwindV4Source({
-                    projectRoot,
-                    cwd: projectRoot,
-                    base: cssBase,
-                    css: code,
-                    cssSources: [{ file: cssFile, base: cssBase, css: code, dependencies: [cssFile] }]
-                });
-                const generator = createWeappTailwindcssGenerator(source);
-                const generated = await generator.generate({
-                    target: pipeline.target === 'wx' ? 'weapp' : 'web',
-                    scanSources: true,
-                    candidates: [],
-                    styleOptions: pipeline.target === 'wx' ? wxStyleOptions : undefined
-                });
-                for (const className of generated.classSet)
-                    pipeline.runtimeClassSet.add(className);
-                for (const dependency of generated.dependencies)
-                    this.addWatchFile(dependency);
-                return generated.css;
-            },
-            async renderChunk(code, chunk) {
-                if (pipeline.target !== 'wx')
-                    return;
-                return await pipeline.transformWxClassNames(code, chunk.fileName);
-            },
-            async generateBundle(_, bundle) {
-                if (pipeline.target !== 'wx')
-                    return;
-                const core = pipeline.getWxContext();
-                await Promise.all(Object.entries(bundle).map(async ([fileName, item]) => {
-                    if (item.type === 'asset' && fileName.endsWith('.css')) {
-                        await transformWxssAsset(core, item);
-                    }
-                }));
-            }
-        };
+    /** Retains Vite's root for resolving later CSS transforms and changed-file notifications. */
+    resolveWx(config) {
+        this.root = config.root;
     }
-    getProjectRoot() {
-        if (!this.projectRoot)
-            throw new Error('vite-plugin-taro CSS pipeline was used before configuration resolved.');
-        return this.projectRoot;
+    /** Creates one validator per Tailwind entry and refreshes the shared upstream WX transformer. */
+    async registerCssEntry(id, source) {
+        const file = resolveFile(id, this.getRoot());
+        if (this.entries.get(file)?.source === source)
+            return;
+        const base = path.dirname(file);
+        const resolved = await resolveTailwindV4Source({
+            projectRoot: this.getRoot(),
+            cwd: this.getRoot(),
+            base,
+            baseFallbacks: [resolvePackageFile()],
+            css: source,
+            cssSources: [{ file, base, css: source, dependencies: [file] }]
+        });
+        this.entries.set(file, { source, generator: createWeappTailwindcssGenerator(resolved) });
+        this.wxContext = createContext({
+            appType: 'taro',
+            cssEntries: [...this.entries.keys()],
+            tailwindcssBasedir: this.getRoot(),
+            generator: { target: 'weapp' },
+            ...wxStyleOptions,
+            logLevel: 'silent'
+        });
     }
+    /** Incrementally checks changed source files for utilities absent from the completed WX build. */
+    async hasAddedCandidates(files) {
+        for (const input of files) {
+            const file = resolveFile(input, this.getRoot());
+            if (!/\.[cm]?[jt]sx?$/.test(file))
+                continue;
+            const source = await fs.readFile(file, 'utf8');
+            if (this.sourceCache.get(file) === source)
+                continue;
+            this.sourceCache.set(file, source);
+            const extracted = await extractSourceCandidates(source, path.extname(file).slice(1));
+            for (const { generator } of this.entries.values()) {
+                const candidates = await generator.validateCandidates(extracted);
+                // Native WX patches bypass Vite; a new utility therefore requires synchronized WXSS first.
+                for (const candidate of candidates)
+                    if (!this.builtClassSet.has(candidate))
+                        return true;
+            }
+        }
+        return false;
+    }
+    /** Returns the initialized WX transformer and detects invalid lifecycle ordering. */
     getWxContext() {
         if (!this.wxContext)
-            throw new Error('vite-plugin-taro expected a resolved WeChat CSS pipeline.');
+            throw new Error('WX CSS pipeline was used before Vite resolved.');
         return this.wxContext;
     }
+    /** Returns the resolved project root and detects use before Vite configuration. */
+    getRoot() {
+        if (!this.root)
+            throw new Error('WX CSS pipeline was used before Vite resolved.');
+        return this.root;
+    }
 }
-function createWxCssContext(projectRoot) {
-    return createContext({
-        appType: 'taro',
-        tailwindcssBasedir: projectRoot,
-        generator: { target: 'weapp' },
-        ...wxStyleOptions,
-        logLevel: 'silent'
-    });
-}
-async function transformWxssAsset(core, item) {
-    const result = await core.transformWxss(getAssetSource(item), { isMainChunk: true });
-    item.source = result.css;
-}
-function shouldGenerateTailwindCss(code) {
-    const tailwindEntryImportPattern = /@(import|reference)\s+(?:url\(\s*)?(?:["'])tailwindcss(?:\/(?:theme|preflight|utilities)(?:\.css)?)?(?:["'])/;
-    return code.includes('tailwindcss') && tailwindEntryImportPattern.test(code);
-}
-function isCssModuleId(id) {
-    return /\.(?:css|scss|sass|less|styl|stylus)(?:$|[?#])/.test(id);
-}
-function getAssetSource(item) {
-    if (typeof item.source === 'string')
-        return item.source;
-    return item.source ? new TextDecoder().decode(item.source) : '';
+/** Identifies style modules that establish a Tailwind design system. */
+function isTailwindCssEntry(code, id) {
+    return (/\.(?:css|scss|sass|less|styl|stylus)(?:$|[?#])/.test(id) &&
+        /@(?:import|reference)\s+(?:url\(\s*)?["']tailwindcss(?:\/[^"']*)?["']/.test(code));
 }
-function resolveCssFile(id, root) {
-    const normalizedId = normalizeModuleId(id);
-    const cleanId = normalizedId.startsWith('/@fs/') ? normalizedId.slice('/@fs'.length) : normalizedId;
-    return path.isAbsolute(cleanId) ? cleanId : path.resolve(root, cleanId);
+/** Converts Vite IDs, including /@fs/ IDs and query strings, into normalized absolute paths. */
+function resolveFile(id, root) {
+    const normalized = normalizeModuleId(id).replace(/[?#].*$/, '');
+    const file = normalized.startsWith('/@fs/') ? normalized.slice('/@fs'.length) : normalized;
+    return normalizeModuleId(path.resolve(root, file));
 }

package/dist/node/targets/wx/companion-assets.d.ts

@@ -13,6 +13,7 @@ type WxAssetEmitter = {
         fileName: string;
         source: WxAssetSource;
     }): string;
+    warn(message: string): void;
 };
-export declare function emitWxCompanionAssets(emitter: WxAssetEmitter, bundle: WxBundle, context: BuildContext): void;
+export declare function emitWxCompanionAssets(emitter: WxAssetEmitter, bundle: WxBundle, context: BuildContext): Promise<void>;
 export {};

package/dist/node/targets/wx/companion-assets.js

@@ -5,16 +5,22 @@ import { normalizeModuleId } from '../../utils/modules.js';
 import { packageRequire } from '../../utils/packages.js';
 const taroWxComponentsPath = packageRequire.resolve('@tarojs/plugin-platform-weapp/dist/components-react');
 const templateBuilder = createWxTemplateBuilder();
-export function emitWxCompanionAssets(emitter, bundle, context) {
-    for (const asset of createWxCompanionAssets(bundle, context)) {
+export async function emitWxCompanionAssets(emitter, bundle, context) {
+    for (const asset of await createWxCompanionAssets(bundle, context)) {
+        if (!asset)
+            continue;
+        if (asset.source === undefined) {
+            emitter.warn(`[vite-plugin-taro] WX companion asset "${asset.fileName}" is missing its source and was not emitted.`);
+            continue;
+        }
         emitter.emitFile({ type: 'asset', fileName: asset.fileName, source: asset.source });
     }
 }
-function createWxCompanionAssets(bundle, context) {
+async function createWxCompanionAssets(bundle, context) {
     const json = (value) => (context.development ? JSON.stringify(value, null, 2) : JSON.stringify(value));
     return [
         { fileName: 'app.json', source: json(context.project.appConfig) },
-        { fileName: 'app.wxss', source: collectWxBundleStyles(bundle) },
+        { fileName: 'app.wxss', source: await context.css.transformWxss(collectWxBundleStyles(bundle)) },
         {
             fileName: 'base.wxml',
             source: templateBuilder.buildTemplate(collectWxTemplateComponentConfig(bundle))
@@ -23,7 +29,9 @@ function createWxCompanionAssets(bundle, context) {
         { fileName: 'comp.wxml', source: templateBuilder.buildBaseComponentTemplate('.wxml') },
         { fileName: 'comp.json', source: json(createWxComponentConfig()) },
         { fileName: 'project.config.json', source: json(createWxProjectConfig(context)) },
-        { fileName: 'project.private.config.json', source: json(context.project.projectPrivateConfigJson) },
+        context.project.projectPrivateConfigJson
+            ? { fileName: 'project.private.config.json', source: json(context.project.projectPrivateConfigJson) }
+            : undefined,
         { fileName: 'sitemap.json', source: json(context.project.sitemapJson) },
         ...context.project.pages.flatMap((page) => [
             {

package/dist/node/targets/wx/dev-server/development-session.d.ts

@@ -21,6 +21,7 @@ export declare class WxDevelopmentSession {
     private readonly handleHttpListening;
     private readonly handleWatchedFile;
     private handleBundleOutput;
+    private finalizeAppStyles;
     private handlePatch;
     private handleError;
     private requestFullBuild;

package/dist/node/targets/wx/dev-server/development-session.js

@@ -98,13 +98,10 @@ export class WxDevelopmentSession {
     };
     handleBundleOutput(output) {
         const appStyles = normalizeWxBundleStyles(output);
-        if (appStyles !== undefined)
-            this.snapshot = { ...this.snapshot, latestAppStyles: appStyles };
-        if (isWxFullBuildOutput(output) && this.snapshot.latestAppStyles) {
-            setWxAppStyles(output, this.snapshot.latestAppStyles);
-        }
-        if (!isWxFullBuildOutput(output)) {
+        const fullBuild = isWxFullBuildOutput(output);
+        if (!fullBuild) {
             this.outputQueue.enqueue(async () => {
+                await this.finalizeAppStyles(output, appStyles, false);
                 await transformWxOutputChunks(output);
                 await writeDevelopmentOutput(this.outDir, output);
             });
@@ -114,6 +111,7 @@ export class WxDevelopmentSession {
         setDevelopmentAsset(output, wxUpdateControlFile, this.updateTransport.createControlSource(buildId));
         setDevelopmentAsset(output, wxUpdateFile, 'void 0;\n');
         this.outputQueue.enqueue(async () => {
+            await this.finalizeAppStyles(output, appStyles, true);
             await transformWxOutputChunks(output);
             if (this.snapshot.outputPhase === 'starting') {
                 // The directory is plugin-owned; clearing it once removes stale files from previous protocol designs.
@@ -123,12 +121,23 @@ export class WxDevelopmentSession {
             this.updateTransport.commitFullBuild(buildId);
             await writeDevelopmentOutput(this.outDir, output);
             await copyDirectoryIfExists(this.config.publicDir, this.outDir);
+            await this.context.css.captureFullBuild();
             const moduleCount = this.adapter.registerBundleModules(output);
             this.snapshot = { ...this.snapshot, outputPhase: 'ready' };
             this.initialBundle.resolve();
             this.server.config.logger.info(`[vite-plugin-taro] WX bundle ready (${moduleCount} modules, ${output.length} files)`);
         });
     }
+    async finalizeAppStyles(output, source, fullBuild) {
+        if (source !== undefined) {
+            const transformed = await this.context.css.transformWxss(source);
+            this.snapshot = { ...this.snapshot, latestAppStyles: transformed };
+            setWxAppStyles(output, transformed);
+        }
+        else if (fullBuild && this.snapshot.latestAppStyles) {
+            setWxAppStyles(output, this.snapshot.latestAppStyles);
+        }
+    }
     handlePatch(files, output) {
         if (!isSafeJavaScriptPatch(files, output)) {
             this.requestFullBuild();
@@ -136,7 +145,11 @@ export class WxDevelopmentSession {
         }
         this.adapter.registerPatchModules(output.code);
         this.outputQueue.enqueue(async () => {
-            const transformed = await this.context.css.transformWxClassNames(output.code, output.filename);
+            const transformed = await this.context.css.transformNativePatch(output.code, output.filename, files);
+            if ('requiresFullBuild' in transformed) {
+                this.requestFullBuild();
+                return;
+            }
             const compatibleCode = await transformWxCompatibleJavaScript(transformed.code, output.filename);
             if (this.updateTransport.retainedDeltaCount >= maxRetainedDeltaCount ||
                 this.updateTransport.retainedDeltaBytes + Buffer.byteLength(compatibleCode) >= maxRetainedDeltaBytes) {

package/dist/node/targets/wx/plugin.js

@@ -41,8 +41,8 @@ function createWxTargetPlugin(context) {
         },
         generateBundle: {
             order: 'post',
-            handler(_, bundle) {
-                emitWxCompanionAssets(this, bundle, context);
+            async handler(_, bundle) {
+                await emitWxCompanionAssets(this, bundle, context);
             }
         },
         configureServer: {
@@ -90,6 +90,7 @@ export function createWxViteConfig(context) {
             target: 'es2018',
             assetsInlineLimit: 1024,
             cssCodeSplit: false,
+            // weapp-tailwindcss has no minifier setting; retain Vite's production CSS minification.
             cssMinify: context.development ? false : 'lightningcss',
             minify: !context.development,
             rolldownOptions: {

package/dist/node/vite-plugin.js

@@ -7,14 +7,14 @@ import { createWxTargetPlugins, createWxViteConfig } from './targets/wx/plugin.j
 /** Creates the Vite plugins for the selected Taro target. */
 export default function vitePluginTaro(options) {
     const context = new BuildContext(options);
-    const targetPlugins = context.project.target === 'wx' ? createWxTargetPlugins(context) : createH5TargetPlugins(context);
     return [
         createBuildCoordinator(context),
         createConditionalDirectivePlugin(context),
         createTaroRuntimePlugin(),
-        context.css.plugin,
+        ...context.css.plugins,
         ...react(),
-        ...targetPlugins
+        ...(context.project.target === 'wx' ? createWxTargetPlugins(context) : []),
+        ...(context.project.target === 'h5' ? createH5TargetPlugins(context) : [])
     ];
 }
 /** Establishes build mode and resolved Vite state before target hooks consume the context. */

package/dist/options.d.ts

@@ -16,6 +16,6 @@ export interface VitePluginTaroOptions {
     pages: VitePluginTaroPageOption[];
     appJson: JsonObject;
     projectConfigJson: JsonObject;
-    projectPrivateConfigJson: JsonObject;
+    projectPrivateConfigJson?: JsonObject;
     sitemapJson: JsonObject;
 }

package/dist/runtime/wx/update-client.js

@@ -116,7 +116,8 @@ export function startWxUpdateClient() {
                         batchApply();
                         dispatch({ type: 'batch-executed', targetVersion: command.targetVersion });
                     }
-                    catch {
+                    catch (error) {
+                        console.error('[vite-plugin-taro] WX update execution failed', error);
                         dispatch({ type: 'batch-failed' });
                     }
                     finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-taro",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "author": "sep2",
   "description": "Vite 8 plugin for building one React/Taro codebase for WeChat Mini Program and H5 targets.",
   "type": "module",
@@ -53,6 +53,7 @@
   "dependencies": {
     "@babel/core": "^7.29.7",
     "@rolldown/plugin-babel": "^0.2.3",
+    "@tailwindcss-mangle/engine": "0.1.3",
     "@tarojs/components": "^4.2.0",
     "@tarojs/helper": "^4.2.0",
     "@tarojs/plugin-platform-h5": "^4.2.0",
@@ -65,9 +66,9 @@
     "picocolors": "^1.1.1",
     "react-refresh": "^0.18.0",
     "tailwindcss": "^4.3.2",
-    "weapp-tailwindcss": "^5.1.14",
-    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.3.0",
-    "@tarojs/react": "npm:vite-plugin-taro-react@0.3.0"
+    "weapp-tailwindcss": "5.1.14",
+    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.3.2",
+    "@tarojs/react": "npm:vite-plugin-taro-react@0.3.2"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/node/build-context.ts

@@ -9,7 +9,7 @@ type ProjectContext = Readonly<{
     pages: readonly VitePluginTaroPageOption[]
     appConfig: JsonObject
     projectConfigJson: JsonObject
-    projectPrivateConfigJson: JsonObject
+    projectPrivateConfigJson?: JsonObject
     sitemapJson: JsonObject
 }>
 
@@ -21,6 +21,7 @@ export class BuildContext {
     private resolvedViteConfig: ResolvedConfig | undefined
 
     constructor(options: VitePluginTaroOptions) {
+        this.css = new CssPipeline(options.target)
         this.project = {
             target: options.target,
             appComponentFile: path.resolve(options.app),
@@ -33,7 +34,6 @@ export class BuildContext {
             projectPrivateConfigJson: options.projectPrivateConfigJson,
             sitemapJson: options.sitemapJson
         }
-        this.css = new CssPipeline(options.target)
     }
 
     configure(environment: ConfigEnv): void {
@@ -48,7 +48,6 @@ export class BuildContext {
         }
         if (this.resolvedViteConfig) throw new Error('vite-plugin-taro build context was already resolved.')
         this.resolvedViteConfig = config
-        this.css.resolve(config.root)
     }
 
     get development(): boolean {

package/src/node/css/css-pipeline.ts

@@ -1,9 +1,17 @@
+import fs from 'node:fs/promises'
 import path from 'node:path'
-import type { Plugin } from 'vite'
+import { extractSourceCandidates } from '@tailwindcss-mangle/engine'
+import type { PluginOption, ResolvedConfig } from 'vite'
 import { createContext } from 'weapp-tailwindcss/core'
-import { createWeappTailwindcssGenerator, resolveTailwindV4Source } from 'weapp-tailwindcss/generator'
+import {
+    createWeappTailwindcssGenerator,
+    resolveTailwindV4Source,
+    type WeappTailwindcssGenerator
+} from 'weapp-tailwindcss/generator'
+import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
 import type { VitePluginTaroTarget } from '../../options.ts'
 import { normalizeModuleId } from '../utils/modules.ts'
+import { resolvePackageFile } from '../utils/packages.ts'
 
 const wxStyleOptions = {
     cssCalc: false,
@@ -12,136 +20,152 @@ const wxStyleOptions = {
     px2rpx: true
 } as const
 
-type WxCssContext = ReturnType<typeof createContext>
-type CssTransformResult = { code: string; map: null }
+type WxContext = ReturnType<typeof createContext>
+type CssEntry = { source: string; generator: WeappTailwindcssGenerator }
+type PatchResult = { code: string } | { requiresFullBuild: true }
 
-/** Owns CSS generation and the class-name state shared by normal chunks and literal WX patches. */
+/** Owns Tailwind's Vite integration and native WX patch synchronization. */
 export class CssPipeline {
-    readonly plugin: Plugin
-    private readonly target: VitePluginTaroTarget
-    private readonly runtimeClassSet = new Set<string>()
-    private projectRoot: string | undefined
-    private wxContext: WxCssContext | undefined
-
+    readonly plugins: PluginOption[]
+    // Each Tailwind CSS entry can define a different design system, so additions must pass every relevant validator.
+    private readonly entries = new Map<string, CssEntry>()
+    // Vite can report the same source more than once; avoid repeating extraction and validation.
+    private readonly sourceCache = new Map<string, string>()
+    // Upstream owns WX JavaScript escaping; this context is deliberately reused between patches.
+    private wxContext: WxContext | undefined
+    // CSS transforms arrive after configResolved, so the Vite root is retained for source and module resolution.
+    private root: string | undefined
+    // Only classes represented by a completed WX build are safe to publish in a JavaScript-only patch.
+    private builtClassSet = new Set<string>()
+
+    /** Composes the upstream web/WX plugins and adds candidate tracking only for native WX patches. */
     constructor(target: VitePluginTaroTarget) {
-        this.target = target
-        this.plugin = this.createPlugin()
+        const pipeline = this
+
+        const wx = target === 'wx'
+
+        this.plugins = [
+            wx
+                ? {
+                      name: 'vite-plugin-taro:wx-tailwind-pipeline',
+                      enforce: 'pre',
+                      configResolved(config) {
+                          pipeline.resolveWx(config)
+                      },
+                      async transform(code, id) {
+                          if (!isTailwindCssEntry(code, id)) return
+                          await pipeline.registerCssEntry(id, code)
+                      }
+                  }
+                : undefined,
+            ...(WeappTailwindcss({
+                appType: 'taro',
+                // Route split Tailwind imports around Vite's unresolved production CSS package imports.
+                rewriteCssImports: true,
+                generator: { target: wx ? 'weapp' : 'web' },
+                ...(wx ? wxStyleOptions : {}),
+                logLevel: 'silent'
+            }) ?? [])
+        ]
+    }
+
+    /** Records every utility guaranteed to exist after a successful full WX build. */
+    async captureFullBuild(): Promise<void> {
+        this.sourceCache.clear()
+        // Preserve removed development CSS, matching upstream's append-only HMR default.
+        for (const { generator } of this.entries.values()) {
+            const result = await generator.generate({ scanSources: true })
+            for (const candidate of result.classSet) this.builtClassSet.add(candidate)
+        }
     }
 
-    resolve(projectRoot: string): void {
-        if (this.projectRoot) throw new Error('vite-plugin-taro CSS pipeline was already resolved.')
-        this.projectRoot = projectRoot
-        this.wxContext = this.target === 'wx' ? createWxCssContext(projectRoot) : undefined
+    /** Applies upstream mini-program compatibility transforms to Taro's fully materialized WXSS. */
+    async transformWxss(code: string): Promise<string> {
+        return (await this.getWxContext().transformWxss(code)).css
     }
 
-    async transformWxClassNames(code: string, filename: string): Promise<CssTransformResult> {
-        if (!this.wxContext || this.runtimeClassSet.size === 0) return { code, map: null }
-        const result = await this.wxContext.transformJs(code, {
-            runtimeSet: this.runtimeClassSet,
+    /** Escapes a JavaScript-only WX patch, or rejects it when its utilities require new WXSS. */
+    async transformNativePatch(code: string, filename: string, files: string[]): Promise<PatchResult> {
+        if (await this.hasAddedCandidates(files)) return { requiresFullBuild: true }
+        const result = await this.getWxContext().transformJs(code, {
+            runtimeSet: this.builtClassSet,
             filename,
             generateMap: false
         })
-        return { code: result.code, map: null }
+        return { code: result.code }
     }
 
-    private createPlugin(): Plugin {
-        const pipeline = this
-        return {
-            name: 'vite-plugin-taro:css',
-            enforce: 'pre',
-
-            buildStart() {
-                pipeline.runtimeClassSet.clear()
-            },
-
-            async transform(code, id) {
-                if (!isCssModuleId(id) || !shouldGenerateTailwindCss(code)) return
-
-                const projectRoot = pipeline.getProjectRoot()
-                const cssFile = resolveCssFile(id, projectRoot)
-                const cssBase = path.dirname(cssFile)
-                const source = await resolveTailwindV4Source({
-                    projectRoot,
-                    cwd: projectRoot,
-                    base: cssBase,
-                    css: code,
-                    cssSources: [{ file: cssFile, base: cssBase, css: code, dependencies: [cssFile] }]
-                })
-                const generator = createWeappTailwindcssGenerator(source)
-                const generated = await generator.generate({
-                    target: pipeline.target === 'wx' ? 'weapp' : 'web',
-                    scanSources: true,
-                    candidates: [],
-                    styleOptions: pipeline.target === 'wx' ? wxStyleOptions : undefined
-                })
-
-                for (const className of generated.classSet) pipeline.runtimeClassSet.add(className)
-                for (const dependency of generated.dependencies) this.addWatchFile(dependency)
-                return generated.css
-            },
-
-            async renderChunk(code, chunk) {
-                if (pipeline.target !== 'wx') return
-                return await pipeline.transformWxClassNames(code, chunk.fileName)
-            },
-
-            async generateBundle(_, bundle) {
-                if (pipeline.target !== 'wx') return
-                const core = pipeline.getWxContext()
-                await Promise.all(
-                    Object.entries(bundle).map(async ([fileName, item]) => {
-                        if (item.type === 'asset' && fileName.endsWith('.css')) {
-                            await transformWxssAsset(core, item)
-                        }
-                    })
-                )
-            }
-        }
+    /** Retains Vite's root for resolving later CSS transforms and changed-file notifications. */
+    private resolveWx(config: ResolvedConfig): void {
+        this.root = config.root
     }
 
-    private getProjectRoot(): string {
-        if (!this.projectRoot) throw new Error('vite-plugin-taro CSS pipeline was used before configuration resolved.')
-        return this.projectRoot
+    /** Creates one validator per Tailwind entry and refreshes the shared upstream WX transformer. */
+    private async registerCssEntry(id: string, source: string): Promise<void> {
+        const file = resolveFile(id, this.getRoot())
+        if (this.entries.get(file)?.source === source) return
+        const base = path.dirname(file)
+        const resolved = await resolveTailwindV4Source({
+            projectRoot: this.getRoot(),
+            cwd: this.getRoot(),
+            base,
+            baseFallbacks: [resolvePackageFile()],
+            css: source,
+            cssSources: [{ file, base, css: source, dependencies: [file] }]
+        })
+        this.entries.set(file, { source, generator: createWeappTailwindcssGenerator(resolved) })
+        this.wxContext = createContext({
+            appType: 'taro',
+            cssEntries: [...this.entries.keys()],
+            tailwindcssBasedir: this.getRoot(),
+            generator: { target: 'weapp' },
+            ...wxStyleOptions,
+            logLevel: 'silent'
+        })
     }
 
-    private getWxContext(): WxCssContext {
-        if (!this.wxContext) throw new Error('vite-plugin-taro expected a resolved WeChat CSS pipeline.')
-        return this.wxContext
+    /** Incrementally checks changed source files for utilities absent from the completed WX build. */
+    private async hasAddedCandidates(files: string[]): Promise<boolean> {
+        for (const input of files) {
+            const file = resolveFile(input, this.getRoot())
+            if (!/\.[cm]?[jt]sx?$/.test(file)) continue
+            const source = await fs.readFile(file, 'utf8')
+            if (this.sourceCache.get(file) === source) continue
+            this.sourceCache.set(file, source)
+            const extracted = await extractSourceCandidates(source, path.extname(file).slice(1))
+            for (const { generator } of this.entries.values()) {
+                const candidates = await generator.validateCandidates(extracted)
+                // Native WX patches bypass Vite; a new utility therefore requires synchronized WXSS first.
+                for (const candidate of candidates) if (!this.builtClassSet.has(candidate)) return true
+            }
+        }
+        return false
     }
-}
 
-function createWxCssContext(projectRoot: string): WxCssContext {
-    return createContext({
-        appType: 'taro',
-        tailwindcssBasedir: projectRoot,
-        generator: { target: 'weapp' },
-        ...wxStyleOptions,
-        logLevel: 'silent'
-    })
-}
-
-async function transformWxssAsset(core: WxCssContext, item: { source?: string | Uint8Array }): Promise<void> {
-    const result = await core.transformWxss(getAssetSource(item), { isMainChunk: true })
-    item.source = result.css
-}
-
-function shouldGenerateTailwindCss(code: string): boolean {
-    const tailwindEntryImportPattern =
-        /@(import|reference)\s+(?:url\(\s*)?(?:["'])tailwindcss(?:\/(?:theme|preflight|utilities)(?:\.css)?)?(?:["'])/
-    return code.includes('tailwindcss') && tailwindEntryImportPattern.test(code)
-}
+    /** Returns the initialized WX transformer and detects invalid lifecycle ordering. */
+    private getWxContext(): WxContext {
+        if (!this.wxContext) throw new Error('WX CSS pipeline was used before Vite resolved.')
+        return this.wxContext
+    }
 
-function isCssModuleId(id: string): boolean {
-    return /\.(?:css|scss|sass|less|styl|stylus)(?:$|[?#])/.test(id)
+    /** Returns the resolved project root and detects use before Vite configuration. */
+    private getRoot(): string {
+        if (!this.root) throw new Error('WX CSS pipeline was used before Vite resolved.')
+        return this.root
+    }
 }
 
-function getAssetSource(item: { source?: string | Uint8Array }): string {
-    if (typeof item.source === 'string') return item.source
-    return item.source ? new TextDecoder().decode(item.source) : ''
+/** Identifies style modules that establish a Tailwind design system. */
+function isTailwindCssEntry(code: string, id: string): boolean {
+    return (
+        /\.(?:css|scss|sass|less|styl|stylus)(?:$|[?#])/.test(id) &&
+        /@(?:import|reference)\s+(?:url\(\s*)?["']tailwindcss(?:\/[^"']*)?["']/.test(code)
+    )
 }
 
-function resolveCssFile(id: string, root: string): string {
-    const normalizedId = normalizeModuleId(id)
-    const cleanId = normalizedId.startsWith('/@fs/') ? normalizedId.slice('/@fs'.length) : normalizedId
-    return path.isAbsolute(cleanId) ? cleanId : path.resolve(root, cleanId)
+/** Converts Vite IDs, including /@fs/ IDs and query strings, into normalized absolute paths. */
+function resolveFile(id: string, root: string): string {
+    const normalized = normalizeModuleId(id).replace(/[?#].*$/, '')
+    const file = normalized.startsWith('/@fs/') ? normalized.slice('/@fs'.length) : normalized
+    return normalizeModuleId(path.resolve(root, file))
 }

package/src/node/targets/wx/companion-assets.ts

@@ -19,6 +19,7 @@ export type WxBundle = Record<
 
 type WxAssetEmitter = {
     emitFile(asset: { type: 'asset'; fileName: string; source: WxAssetSource }): string
+    warn(message: string): void
 }
 
 type WxTemplateComponentConfig = {
@@ -31,21 +32,32 @@ type WxTemplateComponentConfig = {
 const taroWxComponentsPath = packageRequire.resolve('@tarojs/plugin-platform-weapp/dist/components-react')
 const templateBuilder = createWxTemplateBuilder()
 
-export function emitWxCompanionAssets(emitter: WxAssetEmitter, bundle: WxBundle, context: BuildContext): void {
-    for (const asset of createWxCompanionAssets(bundle, context)) {
+export async function emitWxCompanionAssets(
+    emitter: WxAssetEmitter,
+    bundle: WxBundle,
+    context: BuildContext
+): Promise<void> {
+    for (const asset of await createWxCompanionAssets(bundle, context)) {
+        if (!asset) continue
+        if (asset.source === undefined) {
+            emitter.warn(
+                `[vite-plugin-taro] WX companion asset "${asset.fileName}" is missing its source and was not emitted.`
+            )
+            continue
+        }
         emitter.emitFile({ type: 'asset', fileName: asset.fileName, source: asset.source })
     }
 }
 
-function createWxCompanionAssets(
+async function createWxCompanionAssets(
     bundle: WxBundle,
     context: BuildContext
-): { fileName: string; source: WxAssetSource }[] {
+): Promise<({ fileName: string; source: WxAssetSource } | undefined)[]> {
     const json = (value: JsonObject) => (context.development ? JSON.stringify(value, null, 2) : JSON.stringify(value))
 
     return [
         { fileName: 'app.json', source: json(context.project.appConfig) },
-        { fileName: 'app.wxss', source: collectWxBundleStyles(bundle) },
+        { fileName: 'app.wxss', source: await context.css.transformWxss(collectWxBundleStyles(bundle)) },
         {
             fileName: 'base.wxml',
             source: templateBuilder.buildTemplate(collectWxTemplateComponentConfig(bundle))
@@ -54,7 +66,9 @@ function createWxCompanionAssets(
         { fileName: 'comp.wxml', source: templateBuilder.buildBaseComponentTemplate('.wxml') },
         { fileName: 'comp.json', source: json(createWxComponentConfig()) },
         { fileName: 'project.config.json', source: json(createWxProjectConfig(context)) },
-        { fileName: 'project.private.config.json', source: json(context.project.projectPrivateConfigJson) },
+        context.project.projectPrivateConfigJson
+            ? { fileName: 'project.private.config.json', source: json(context.project.projectPrivateConfigJson) }
+            : undefined,
         { fileName: 'sitemap.json', source: json(context.project.sitemapJson) },
         ...context.project.pages.flatMap((page) => [
             {

package/src/node/targets/wx/dev-server/development-session.ts

@@ -131,13 +131,11 @@ export class WxDevelopmentSession {
 
     private handleBundleOutput(output: WxOutputFile[]): void {
         const appStyles = normalizeWxBundleStyles(output)
-        if (appStyles !== undefined) this.snapshot = { ...this.snapshot, latestAppStyles: appStyles }
-        if (isWxFullBuildOutput(output) && this.snapshot.latestAppStyles) {
-            setWxAppStyles(output, this.snapshot.latestAppStyles)
-        }
+        const fullBuild = isWxFullBuildOutput(output)
 
-        if (!isWxFullBuildOutput(output)) {
+        if (!fullBuild) {
             this.outputQueue.enqueue(async () => {
+                await this.finalizeAppStyles(output, appStyles, false)
                 await transformWxOutputChunks(output)
                 await writeDevelopmentOutput(this.outDir, output)
             })
@@ -148,6 +146,7 @@ export class WxDevelopmentSession {
         setDevelopmentAsset(output, wxUpdateControlFile, this.updateTransport.createControlSource(buildId))
         setDevelopmentAsset(output, wxUpdateFile, 'void 0;\n')
         this.outputQueue.enqueue(async () => {
+            await this.finalizeAppStyles(output, appStyles, true)
             await transformWxOutputChunks(output)
             if (this.snapshot.outputPhase === 'starting') {
                 // The directory is plugin-owned; clearing it once removes stale files from previous protocol designs.
@@ -157,6 +156,7 @@ export class WxDevelopmentSession {
             this.updateTransport.commitFullBuild(buildId)
             await writeDevelopmentOutput(this.outDir, output)
             await copyDirectoryIfExists(this.config.publicDir, this.outDir)
+            await this.context.css.captureFullBuild()
             const moduleCount = this.adapter.registerBundleModules(output)
             this.snapshot = { ...this.snapshot, outputPhase: 'ready' }
             this.initialBundle.resolve()
@@ -166,6 +166,20 @@ export class WxDevelopmentSession {
         })
     }
 
+    private async finalizeAppStyles(
+        output: WxOutputFile[],
+        source: string | undefined,
+        fullBuild: boolean
+    ): Promise<void> {
+        if (source !== undefined) {
+            const transformed = await this.context.css.transformWxss(source)
+            this.snapshot = { ...this.snapshot, latestAppStyles: transformed }
+            setWxAppStyles(output, transformed)
+        } else if (fullBuild && this.snapshot.latestAppStyles) {
+            setWxAppStyles(output, this.snapshot.latestAppStyles)
+        }
+    }
+
     private handlePatch(files: string[], output: WxDevEngineUpdate): boolean {
         if (!isSafeJavaScriptPatch(files, output)) {
             this.requestFullBuild()
@@ -174,7 +188,11 @@ export class WxDevelopmentSession {
 
         this.adapter.registerPatchModules(output.code)
         this.outputQueue.enqueue(async () => {
-            const transformed = await this.context.css.transformWxClassNames(output.code, output.filename)
+            const transformed = await this.context.css.transformNativePatch(output.code, output.filename, files)
+            if ('requiresFullBuild' in transformed) {
+                this.requestFullBuild()
+                return
+            }
             const compatibleCode = await transformWxCompatibleJavaScript(transformed.code, output.filename)
             if (
                 this.updateTransport.retainedDeltaCount >= maxRetainedDeltaCount ||

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

@@ -53,8 +53,8 @@ function createWxTargetPlugin(context: BuildContext): Plugin {
 
         generateBundle: {
             order: 'post',
-            handler(_, bundle) {
-                emitWxCompanionAssets(this, bundle as WxBundle, context)
+            async handler(_, bundle) {
+                await emitWxCompanionAssets(this, bundle as WxBundle, context)
             }
         },
 
@@ -107,6 +107,7 @@ export function createWxViteConfig(context: BuildContext): UserConfig {
             target: 'es2018',
             assetsInlineLimit: 1024,
             cssCodeSplit: false,
+            // weapp-tailwindcss has no minifier setting; retain Vite's production CSS minification.
             cssMinify: context.development ? false : 'lightningcss',
             minify: !context.development,
             rolldownOptions: {

package/src/node/vite-plugin.ts

@@ -10,16 +10,15 @@ import { createWxTargetPlugins, createWxViteConfig } from './targets/wx/plugin.t
 /** 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,
+        ...context.css.plugins,
         ...react(),
-        ...targetPlugins
+        ...(context.project.target === 'wx' ? createWxTargetPlugins(context) : []),
+        ...(context.project.target === 'h5' ? createH5TargetPlugins(context) : [])
     ]
 }
 

package/src/options.ts

@@ -20,6 +20,6 @@ export interface VitePluginTaroOptions {
     pages: VitePluginTaroPageOption[]
     appJson: JsonObject
     projectConfigJson: JsonObject
-    projectPrivateConfigJson: JsonObject
+    projectPrivateConfigJson?: JsonObject
     sitemapJson: JsonObject
 }

package/src/runtime/wx/update-client.ts

@@ -168,7 +168,8 @@ export function startWxUpdateClient(): void {
                     try {
                         batchApply()
                         dispatch({ type: 'batch-executed', targetVersion: command.targetVersion })
-                    } catch {
+                    } catch (error) {
+                        console.error('[vite-plugin-taro] WX update execution failed', error)
                         dispatch({ type: 'batch-failed' })
                     } finally {
                         bridge.endUpdate?.()