fix: speed up v3 vite watch runtime updates

Author: sonofmagic

.changeset/fix-v3-vite-watch-runtime.md

@@ -0,0 +1,5 @@
+---
+"weapp-tailwindcss": patch
+---
+
+修复 Tailwind CSS v3 在 Vite watch 热更新中因源码类名变化反复触发完整 runtime extract 导致 HMR 变慢的问题。v3 首轮仍保留完整 runtime 基线，后续 watch 轮次按文件增量更新源码候选类，避免已删除源码类继续污染 CSS，同时保留 safelist 等非源码基线类。

packages/weapp-tailwindcss/src/bundlers/vite/generate-bundle.ts

@@ -139,12 +139,10 @@ export function createGenerateBundleHook(context: GenerateBundleContext) {
     const filteredGeneratorCandidates = shouldFilterTailwindV4MiniProgramCandidates
       ? filterUnsupportedMiniProgramTailwindV4Candidates(collectedGeneratorCandidates)
       : collectedGeneratorCandidates
-    const generatorRuntime = collectLegacyContainerCompatCandidates(
+    let generatorRuntime = collectLegacyContainerCompatCandidates(
       sourceCandidates,
       filteredGeneratorCandidates,
     )
-    const generatorCandidateSignature = createCandidateSignature(generatorRuntime)
-    recordGeneratorCandidates?.(generatorRuntime)
     let transformRuntime = runtime
     if (runtimeState.twPatcher.majorVersion === 3 && generatorRuntime.size > 0) {
       const cssEntries = snapshot.entries.filter(entry =>
@@ -163,10 +161,20 @@ export function createGenerateBundleHook(context: GenerateBundleContext) {
           debug,
         })
         if (validatedRuntime.size > 0) {
-          transformRuntime = new Set([...runtime, ...validatedRuntime])
+          generatorRuntime = collectLegacyContainerCompatCandidates(
+            sourceCandidates,
+            validatedRuntime,
+          )
+          transformRuntime = generatorRuntime
+        }
+        else {
+          generatorRuntime = validatedRuntime
+          transformRuntime = validatedRuntime
         }
       }
     }
+    const generatorCandidateSignature = createCandidateSignature(generatorRuntime)
+    recordGeneratorCandidates?.(generatorRuntime)
     const defaultTemplateHandlerOptions = {
       runtimeSet: transformRuntime,
     }

packages/weapp-tailwindcss/src/bundlers/vite/incremental-runtime-class-set.ts

@@ -18,10 +18,14 @@ type ExtractRawCandidateResult = Awaited<ReturnType<typeof extractRawCandidatesW
 type ExtractRawCandidatesFn = (content: string, extension?: string) => Promise<ExtractRawCandidateResult>
 
 export interface BundleRuntimeClassSetManager {
-  sync: (patcher: TailwindcssPatcherLike, snapshot: BundleSnapshot) => Promise<Set<string>>
+  sync: (patcher: TailwindcssPatcherLike, snapshot: BundleSnapshot, options?: BundleRuntimeClassSetSyncOptions) => Promise<Set<string>>
   reset: () => Promise<void>
 }
 
+export interface BundleRuntimeClassSetSyncOptions {
+  baseClassSet?: Set<string> | undefined
+}
+
 interface CreateBundleRuntimeClassSetManagerOptions {
   extractCandidates?: ExtractValidCandidatesFn
   extractRawCandidates?: ExtractRawCandidatesFn
@@ -71,7 +75,6 @@ function createCandidateValidationSource(candidates: Iterable<string>) {
 
 function removeCandidateSet(
   candidateCountByClass: Map<string, number>,
-  runtimeSet: Set<string>,
   candidates: Set<string>,
 ) {
   for (const className of candidates) {
@@ -81,7 +84,6 @@ function removeCandidateSet(
     }
     if (count <= 1) {
       candidateCountByClass.delete(className)
-      runtimeSet.delete(className)
       continue
     }
     candidateCountByClass.set(className, count - 1)
@@ -90,23 +92,42 @@ function removeCandidateSet(
 
 function addCandidateSet(
   candidateCountByClass: Map<string, number>,
-  runtimeSet: Set<string>,
   candidates: Set<string>,
 ) {
   for (const className of candidates) {
     const nextCount = (candidateCountByClass.get(className) ?? 0) + 1
     candidateCountByClass.set(className, nextCount)
-    runtimeSet.add(className)
   }
 }
 
+function createRuntimeClassSet(
+  baseClassSet: Set<string>,
+  candidateCountByClass: Map<string, number>,
+) {
+  return new Set([
+    ...baseClassSet,
+    ...candidateCountByClass.keys(),
+  ])
+}
+
+function createNonSourceBaseClassSet(
+  baseClassSet: Set<string>,
+  candidateCountByClass: Map<string, number>,
+) {
+  const nextBaseClassSet = new Set(baseClassSet)
+  for (const candidate of candidateCountByClass.keys()) {
+    nextBaseClassSet.delete(candidate)
+  }
+  return nextBaseClassSet
+}
+
 export function createBundleRuntimeClassSetManager(
   options: CreateBundleRuntimeClassSetManagerOptions = {},
 ): BundleRuntimeClassSetManager {
   const customExtractCandidates = options.extractCandidates
   const extractCandidates = customExtractCandidates ?? extractValidCandidates
   const extractRawCandidates = options.extractRawCandidates ?? extractRawCandidatesWithPositions
-  const runtimeSet = new Set<string>()
+  let baseClassSet = new Set<string>()
   const candidateCountByClass = new Map<string, number>()
   const candidatesByFile = new Map<string, Set<string>>()
   const candidateValidityCache = new Map<string, boolean>()
@@ -115,7 +136,7 @@ export function createBundleRuntimeClassSetManager(
   let designSystemPromise: Promise<TailwindV4DesignSystem> | undefined
 
   async function reset() {
-    runtimeSet.clear()
+    baseClassSet = new Set<string>()
     candidateCountByClass.clear()
     candidatesByFile.clear()
     candidateValidityCache.clear()
@@ -169,6 +190,13 @@ export function createBundleRuntimeClassSetManager(
       return
     }
 
+    if (patcher.majorVersion === 3 && !customExtractCandidates) {
+      for (const candidate of unknownCandidates) {
+        candidateValidityCache.set(candidate, true)
+      }
+      return
+    }
+
     const context = await resolveValidationContextCached(patcher)
     if (!customExtractCandidates) {
       try {
@@ -206,6 +234,7 @@ export function createBundleRuntimeClassSetManager(
   async function sync(
     patcher: TailwindcssPatcherLike,
     snapshot: BundleSnapshot,
+    options: BundleRuntimeClassSetSyncOptions = {},
   ) {
     const nextSignature = getRuntimeClassSetSignature(patcher) ?? 'runtime:missing'
     const runtimeEntries = createRuntimeEntries(snapshot)
@@ -219,12 +248,13 @@ export function createBundleRuntimeClassSetManager(
     }
 
     runtimeSignature = nextSignature
+    const nextBaseClassSet = options.baseClassSet
 
     for (const [file, previousCandidates] of candidatesByFile) {
       if (currentRuntimeFiles.has(file)) {
         continue
       }
-      removeCandidateSet(candidateCountByClass, runtimeSet, previousCandidates)
+      removeCandidateSet(candidateCountByClass, previousCandidates)
       candidatesByFile.delete(file)
     }
 
@@ -233,7 +263,10 @@ export function createBundleRuntimeClassSetManager(
       : [...collectChangedRuntimeFiles(snapshot)]
 
     if (changedRuntimeFiles.length === 0) {
-      return new Set(runtimeSet)
+      if (nextBaseClassSet) {
+        baseClassSet = createNonSourceBaseClassSet(nextBaseClassSet, candidateCountByClass)
+      }
+      return createRuntimeClassSet(baseClassSet, candidateCountByClass)
     }
 
     const rawCandidatesByFile = new Map<string, Set<string>>()
@@ -261,7 +294,7 @@ export function createBundleRuntimeClassSetManager(
       const nextRawCandidates = rawCandidatesByFile.get(file)
       const previousCandidates = candidatesByFile.get(file)
       if (previousCandidates) {
-        removeCandidateSet(candidateCountByClass, runtimeSet, previousCandidates)
+        removeCandidateSet(candidateCountByClass, previousCandidates)
       }
 
       if (!nextRawCandidates || nextRawCandidates.size === 0) {
@@ -279,10 +312,15 @@ export function createBundleRuntimeClassSetManager(
         continue
       }
 
-      addCandidateSet(candidateCountByClass, runtimeSet, nextCandidates)
+      addCandidateSet(candidateCountByClass, nextCandidates)
       candidatesByFile.set(file, nextCandidates)
     }
 
+    if (nextBaseClassSet) {
+      baseClassSet = createNonSourceBaseClassSet(nextBaseClassSet, candidateCountByClass)
+    }
+    const runtimeSet = createRuntimeClassSet(baseClassSet, candidateCountByClass)
+
     debug(
       'incremental runtime set synced, changedFiles=%d rawCandidates=%d validateMisses=%d runtimeSize=%d trackedFiles=%d',
       changedRuntimeFiles.length,

packages/weapp-tailwindcss/src/bundlers/vite/runtime-class-set.ts

@@ -136,6 +136,28 @@ export function createViteRuntimeClassSet(options: CreateViteRuntimeClassSetOpti
       }
     }
 
+    if (runtimeState.twPatcher.majorVersion === 3 && !forceRuntimeRefresh) {
+      try {
+        let baseClassSet: Set<string> | undefined
+        if (!runtimeSet || shouldRefreshPatcher) {
+          baseClassSet = await collectRuntimeClassSet(runtimeState.twPatcher, {
+            force: true,
+            skipRefresh: shouldRefreshPatcher,
+            clearCache: shouldRefreshPatcher,
+          })
+        }
+        const nextRuntimeSet = await bundleRuntimeClassSetManager.sync(runtimeState.twPatcher, snapshot, {
+          baseClassSet,
+        })
+        runtimeSet = nextRuntimeSet
+        return nextRuntimeSet
+      }
+      catch (error) {
+        debug('incremental runtime set sync failed, fallback to full collect: %O', error)
+        await bundleRuntimeClassSetManager.reset()
+      }
+    }
+
     if (!forceRuntimeRefresh && !invalidation.changed && !forceCollectBySource && runtimeSet) {
       return runtimeSet
     }

packages/weapp-tailwindcss/test/bundlers/vite-incremental-runtime-class-set.unit.test.ts

@@ -35,6 +35,16 @@ function createPatcher(projectRoot: string) {
   } as any
 }
 
+function createV3Patcher() {
+  return {
+    majorVersion: 3,
+    patch: vi.fn(async () => ({})),
+    getClassSet: vi.fn(async () => new Set<string>()),
+    extract: vi.fn(async () => ({ classSet: new Set<string>() })),
+    options: {},
+  } as any
+}
+
 describe('bundlers/vite incremental runtime class set', () => {
   let tempRoot = ''
 
@@ -433,4 +443,51 @@ describe('bundlers/vite incremental runtime class set', () => {
     await manager.sync(patcher, secondSnapshot)
     expect(extractCandidates).toHaveBeenCalledTimes(2)
   })
+
+  it('keeps v3 non-source baseline classes while replacing changed source candidates', async () => {
+    const opts = createOptions()
+    const outDir = '/project/dist'
+    const state = createBundleBuildState()
+    const patcher = createV3Patcher()
+    const extractRawCandidates = vi.fn(async (content: string) => {
+      if (content.includes('bg-blue-500')) {
+        return [{ rawCandidate: 'bg-blue-500' }]
+      }
+      if (content.includes('bg-[#123455]')) {
+        return [{ rawCandidate: 'bg-[#123455]' }]
+      }
+      return []
+    })
+    const manager = createBundleRuntimeClassSetManager({
+      extractRawCandidates,
+    })
+
+    const firstSnapshot = buildBundleSnapshot({
+      'pages/index/index.wxml': {
+        ...createRollupAsset('<view class="bg-blue-500" />'),
+        fileName: 'pages/index/index.wxml',
+      },
+    }, opts, outDir, state)
+
+    const firstRuntimeSet = await manager.sync(patcher, firstSnapshot, {
+      baseClassSet: new Set(['bg-blue-500', 'safelist-only']),
+    })
+
+    expect(firstRuntimeSet).toEqual(new Set(['safelist-only', 'bg-blue-500']))
+
+    updateBundleBuildState(state, firstSnapshot, new Map())
+
+    const secondSnapshot = buildBundleSnapshot({
+      'pages/index/index.wxml': {
+        ...createRollupAsset('<view class="bg-[#123455]" />'),
+        fileName: 'pages/index/index.wxml',
+      },
+    }, opts, outDir, state)
+
+    const secondRuntimeSet = await manager.sync(patcher, secondSnapshot)
+
+    expect(secondRuntimeSet).toEqual(new Set(['safelist-only', 'bg-[#123455]']))
+    expect(secondRuntimeSet.has('bg-blue-500')).toBe(false)
+    expect(extractRawCandidates).toHaveBeenCalledTimes(2)
+  })
 })