fix: speed up tailwind v3 generator reuse

Author: sonofmagic

.changeset/fast-v3-engine-runtime-cache.md

@@ -0,0 +1,5 @@
+---
+"weapp-tailwindcss": patch
+---
+
+修复 Tailwind CSS v3 生成器在 uni-app Vite 热更新中重复清理 Tailwind require cache 导致 wxss 生成缓存失效、增量编译明显变慢的问题。现在 v3 生成器会复用运行时 patch 初始化结果，并在每次生成前主动重置 Tailwind v3 plugin 上下文，避免旧 class 泄漏。

packages/weapp-tailwindcss/src/tailwindcss/v3-engine/generator.ts

@@ -20,6 +20,8 @@ interface TailwindcssPlugin {
   }
 }
 
+const runtimeReadyPromiseCache = new Map<string, Promise<void>>()
+
 interface LegacyContentObject {
   files?: unknown
   relative?: boolean
@@ -109,6 +111,22 @@ function loadTailwindcssPlugin(source: TailwindV3ResolvedSource): TailwindcssPlu
   return typeof plugin === 'function' ? plugin : plugin.default as TailwindcssPlugin
 }
 
+function createRuntimeReadyCacheKey(source: TailwindV3ResolvedSource, rootPath: string | undefined) {
+  return [
+    source.packageName,
+    source.postcssPlugin,
+    rootPath ?? 'missing',
+    source.config ?? 'config:missing',
+    source.cwd,
+  ].join('\0')
+}
+
+function resetTailwindcssPluginContext(plugin: TailwindcssPlugin) {
+  if (plugin.contextRef) {
+    plugin.contextRef.value = []
+  }
+}
+
 function collectClassSet(plugin: TailwindcssPlugin) {
   const classSet = new Set<string>()
   for (const context of plugin.contextRef?.value ?? []) {
@@ -144,9 +162,20 @@ function createRuntimeReadyPromise(source: TailwindV3ResolvedSource) {
       version: 3,
     },
   })
-  return ensureTailwindcssRuntimePatch(patcher, {
+  const cacheKey = createRuntimeReadyCacheKey(source, patcher.packageInfo?.rootPath)
+  const cached = runtimeReadyPromiseCache.get(cacheKey)
+  if (cached) {
+    return cached
+  }
+
+  const task = ensureTailwindcssRuntimePatch(patcher, {
     clearRequireCache: true,
+  }).catch((error) => {
+    runtimeReadyPromiseCache.delete(cacheKey)
+    throw error
   })
+  runtimeReadyPromiseCache.set(cacheKey, task)
+  return task
 }
 
 export function createTailwindV3Engine(source: TailwindV3ResolvedSource): TailwindV3Engine {
@@ -160,6 +189,7 @@ export function createTailwindV3Engine(source: TailwindV3ResolvedSource): Tailwi
       target = 'weapp',
     } = options
     const tailwindcss = loadTailwindcssPlugin(source)
+    resetTailwindcssPluginContext(tailwindcss)
     const tailwindConfig = createTailwindConfig(source, options)
     const result = await postcss([
       tailwindcss(tailwindConfig),

packages/weapp-tailwindcss/test/tailwindcss/v3-engine.test.ts

@@ -1,11 +1,35 @@
+import path from 'node:path'
 import { createTailwindV3Engine, resolveTailwindV3Source, transformTailwindV3CssToWeapp } from '@/tailwindcss/v3-engine'
+import { TailwindcssPatcher } from 'tailwindcss-patch'
 import plugin from 'tailwindcss/plugin'
 
 function compactCss(css: string) {
   return css.replace(/\s+/g, '')
 }
 
 describe('tailwindcss v3 engine', () => {
+  it('reuses runtime patch setup for repeated engines with the same source', async () => {
+    const source = await resolveTailwindV3Source({
+      css: '@tailwind utilities;',
+      base: path.resolve(process.cwd(), 'demo/uni-app-vite-tailwindcss-v3'),
+      config: undefined,
+    })
+    const patchSpy = vi.spyOn(TailwindcssPatcher.prototype, 'patch')
+
+    const first = createTailwindV3Engine(source)
+    const second = createTailwindV3Engine(source)
+
+    try {
+      await first.generate({ candidates: ['bg-blue-500'] })
+      await second.generate({ candidates: ['bg-[#123455]'] })
+
+      expect(patchSpy).toHaveBeenCalledTimes(1)
+    }
+    finally {
+      patchSpy.mockRestore()
+    }
+  })
+
   it('removes browser preflight while keeping utility variables for mini-program output', async () => {
     const source = await resolveTailwindV3Source({
       css: '@tailwind base; @tailwind utilities;',
@@ -162,6 +186,28 @@ describe('tailwindcss v3 engine', () => {
     expect(result.css).toContain('.w-4')
   })
 
+  it('does not leak class cache between repeated generations', async () => {
+    const source = await resolveTailwindV3Source({
+      css: '@tailwind utilities;',
+      base: process.cwd(),
+      config: undefined,
+    })
+    const engine = createTailwindV3Engine(source)
+
+    const first = await engine.generate({
+      candidates: ['bg-blue-500'],
+    })
+    const second = await engine.generate({
+      candidates: ['bg-[#123455]'],
+    })
+
+    expect(first.css).toContain('.bg-blue-500')
+    expect(first.classSet).toEqual(new Set(['bg-blue-500']))
+    expect(second.css).toContain('.bg-_b_h123455_B')
+    expect(second.css).not.toContain('.bg-blue-500')
+    expect(second.classSet).toEqual(new Set(['bg-[#123455]']))
+  })
+
   it('normalizes default export configs before generating plugin components', async () => {
     const source = await resolveTailwindV3Source({
       css: '@tailwind components;',

packages/weapp-tailwindcss/test/watch-hmr-regression.unit.test.ts

@@ -935,7 +935,7 @@ describe('watch-hmr regression cases', () => {
     expect(contentMutation?.mutate(
       [
         'const bgObj = ref({',
-        '  \'bg-[#999999]\':true',
+        '  \'bg-[#232322]\':true',
         '})',
       ].join('\n'),
       payload,
@@ -1063,6 +1063,7 @@ describe('watch-hmr regression cases', () => {
       path.resolve('/repo', 'demo/uni-app-vite-tailwindcss-v3/dist/build/mp-weixin/pages/index/index.wxss'),
       path.resolve('/repo', 'demo/uni-app-vite-tailwindcss-v3/dist/build/mp-weixin/app.wxss'),
     ])
+    expect(uniViteCase?.maxPluginProcessMs).toBe(5000)
 
     expect(mpxV4Case?.outputWxml).toBe(
       path.resolve('/repo', 'demo/mpx-tailwindcss-v4/dist/wx/custom-tab-bar/index.wxml'),

tools/weapp-tailwindcss-scripts/src/watch-hmr-regression/cases/demo/extended.ts

@@ -61,14 +61,10 @@ function mutateUniAppViteV3BgObjKey(
   source: string,
   payload: Parameters<NonNullable<WatchCase['contentMutation']>['mutate']>[1],
 ) {
-  const anchors = [
-    '\'bg-[#999999]\':true',
-    '\'bg-[#4268EA]\':true',
-    '\'bg-[red]\':true',
-  ]
-  const anchor = anchors.find(candidate => source.includes(candidate))
+  const bgObjMatch = /const\s+bgObj\s*=\s*ref\s*\(\s*\{[\s\S]*?\}\s*\)/.exec(source)
+  const anchor = /(['"]bg-\[[^\r\n'"]+\]['"]\s*:\s*true)/.exec(bgObjMatch?.[0] ?? '')?.[1]
   if (!anchor) {
-    throw new Error(`uni-app vite v3 bgObj key anchor not found: ${anchors.join(' | ')}`)
+    throw new Error('uni-app vite v3 bgObj arbitrary bg key anchor not found')
   }
   return mutateVueScriptSetupObjectKeyByAnchor(source, anchor, payload)
 }
@@ -144,6 +140,7 @@ export function buildDemoExtendedCases(baseCwd: string): WatchCase[] {
     project: 'demo/uni-app-vite-tailwindcss-v3',
     group: 'demo',
     requireStableGlobalStyleOnSameClassLiteral: false,
+    maxPluginProcessMs: 5000,
     cwd: path.resolve(baseCwd, 'demo/uni-app-vite-tailwindcss-v3'),
     devScript: 'dev:e2e-watch',
     outputWxml: path.resolve(baseCwd, 'demo/uni-app-vite-tailwindcss-v3/dist/build/mp-weixin/pages/index/index.wxml'),