fix: cache tailwind v3 incremental css generation

Author: sonofmagic

.changeset/v3-incremental-generator-cache.md

@@ -0,0 +1,5 @@
+---
+"weapp-tailwindcss": patch
+---
+
+优化 Tailwind CSS v3 生成器在 Vite 热更新中的增量 CSS 生成路径。现在 v3 生成器在热更新场景会复用同一 source/style/target 下已生成的 CSS，只为新增候选类生成 utilities 片段，减少重复执行完整 Tailwind v3 PostCSS 生成的次数。

packages/weapp-tailwindcss/src/bundlers/shared/generator-css.ts

@@ -271,6 +271,7 @@ export async function generateCssByGenerator(
       const generator = createWeappTailwindcssGenerator(source)
       return generator.generate({
         candidates: runtime,
+        incrementalCache: majorVersion === 3,
         scanSources: majorVersion === 4,
         styleOptions: generatorStyleOptions,
         tailwindcssV3Compatibility: generatorOptions.tailwindcssV3Compatibility,

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

@@ -64,8 +64,29 @@ interface GenerateBundleThis {
   }) => string
 }
 
+function addSiblingCssFile(files: Set<string>, file: string) {
+  if (file.endsWith('.wxml')) {
+    files.add(file.replace(/\.wxml$/, '.wxss'))
+  }
+  else if (file.endsWith('.js')) {
+    files.add(file.replace(/\.js$/, '.wxss'))
+  }
+}
+
+function collectRuntimeLinkedCssFiles(snapshot: BundleSnapshot) {
+  const files = new Set<string>()
+  for (const file of snapshot.runtimeAffectingChangedByType.html) {
+    addSiblingCssFile(files, file)
+  }
+  for (const file of snapshot.runtimeAffectingChangedByType.js) {
+    addSiblingCssFile(files, file)
+  }
+  return files
+}
+
 export function createGenerateBundleHook(context: GenerateBundleContext) {
   const state = createBundleBuildState()
+  const lastCssResultByFile = new Map<string, string>()
   const cssHandlerOptions = createCssHandlerOptionsCache({
     appType: context.opts.appType,
     mainCssChunkMatcher: context.opts.mainCssChunkMatcher,
@@ -184,6 +205,7 @@ export function createGenerateBundleHook(context: GenerateBundleContext) {
       }
     }
     const generatorCandidateSignature = createCandidateSignature(generatorRuntime)
+    const runtimeLinkedCssFiles = collectRuntimeLinkedCssFiles(snapshot)
     recordGeneratorCandidates?.(generatorRuntime)
     const defaultTemplateHandlerOptions = {
       runtimeSet: transformRuntime,
@@ -284,16 +306,34 @@ export function createGenerateBundleHook(context: GenerateBundleContext) {
         const cssRuntimeAffectingSignature = snapshot.runtimeAffectingSignatureByFile.get(file) ?? rawSource
         const cssShareScope = createCssTransformShareScopeKey(opts, file, rawSource)
         const cssHandlerOptions = getCssHandlerOptions(file)
-        const cssRuntimeSignature = createCssRuntimeSignature(runtimeSignature, generatorCandidateSignature)
+        const shouldTrackGeneratorRuntime = !useIncrementalMode
+          || cssHandlerOptions.isMainChunk
+          || processFiles.css.has(file)
+          || runtimeLinkedCssFiles.has(file)
+        const scopedGeneratorCandidateSignature = shouldTrackGeneratorRuntime
+          ? generatorCandidateSignature
+          : 'generator:stable'
+        const cssRuntimeSignature = createCssRuntimeSignature(runtimeSignature, scopedGeneratorCandidateSignature)
         const cssSharedCacheKey = `${cssShareScope}:${cssRuntimeSignature}:${runtimeState.twPatcher.majorVersion ?? 'unknown'}:${cssHandlerOptions.isMainChunk ? '1' : '0'}:${cssRuntimeAffectingSignature}`
+        if (!shouldTrackGeneratorRuntime) {
+          const lastCss = lastCssResultByFile.get(file)
+          if (lastCss != null) {
+            originalSource.source = lastCss
+            markCssAssetProcessed?.(originalSource, file)
+            metrics.css.cacheHits++
+            debug('css replay last result: %s', file)
+            continue
+          }
+        }
         tasks.push(
           processCachedTask<string>({
             cache,
             cacheKey: file,
             hashKey: `${file}:css:${cssRuntimeSignature}:${runtimeState.twPatcher.majorVersion ?? 'unknown'}`,
-            hash: `${getSnapshotHash(snapshot.runtimeAffectingHashByFile, file, cssRuntimeAffectingSignature)}:${generatorCandidateSignature}`,
+            hash: `${getSnapshotHash(snapshot.runtimeAffectingHashByFile, file, cssRuntimeAffectingSignature)}:${scopedGeneratorCandidateSignature}`,
             applyResult(source) {
               originalSource.source = source
+              lastCssResultByFile.set(file, source)
               markCssAssetProcessed?.(originalSource, file)
               if (cssHandlerOptions.isMainChunk) {
                 rememberMainCssSource?.(file, rawSource, cssRuntimeSignature)

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

@@ -1,10 +1,13 @@
+import type { IStyleHandlerOptions } from '@weapp-tailwindcss/postcss/types'
 import type { Config } from 'tailwindcss'
 import type {
   TailwindV3CandidateSource,
   TailwindV3Engine,
   TailwindV3GenerateOptions,
+  TailwindV3GenerateTarget,
   TailwindV3ResolvedSource,
 } from './types'
+import fs from 'node:fs'
 import { createRequire } from 'node:module'
 import postcss from 'postcss'
 import { createTailwindcssPatcher } from '@/tailwindcss/patcher'
@@ -21,6 +24,16 @@ interface TailwindcssPlugin {
 }
 
 const runtimeReadyPromiseCache = new Map<string, Promise<void>>()
+const incrementalGenerateCache = new Map<string, TailwindV3IncrementalGenerateCacheEntry>()
+
+interface TailwindV3IncrementalGenerateCacheEntry {
+  seenCandidates: Set<string>
+  classSet: Set<string>
+  css: string
+  rawCss: string
+  dependencies: string[]
+  target: TailwindV3GenerateTarget
+}
 
 interface LegacyContentObject {
   files?: unknown
@@ -51,6 +64,10 @@ function createRawContentEntries(candidates: Iterable<string>, sources: Tailwind
   return entries
 }
 
+function collectCandidates(candidates: Iterable<string> | undefined) {
+  return new Set(candidates ?? [])
+}
+
 function mergeContent(content: unknown, rawEntries: Array<{ raw: string, extension: string }>) {
   if (isLegacyContentObject(content)) {
     return {
@@ -111,6 +128,51 @@ function loadTailwindcssPlugin(source: TailwindV3ResolvedSource): TailwindcssPlu
   return typeof plugin === 'function' ? plugin : plugin.default as TailwindcssPlugin
 }
 
+function createStableJson(value: unknown): string {
+  if (value === undefined) {
+    return 'undefined'
+  }
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value)
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(item => createStableJson(item)).join(',')}]`
+  }
+  return `{${Object.keys(value).sort().map((key) => {
+    const record = value as Record<string, unknown>
+    return `${JSON.stringify(key)}:${createStableJson(record[key])}`
+  }).join(',')}}`
+}
+
+function createDependencyFingerprint(files: string[]) {
+  return files.map((file) => {
+    try {
+      const stat = fs.statSync(file)
+      return `${file}:${stat.size}:${stat.mtimeMs}`
+    }
+    catch {
+      return `${file}:missing`
+    }
+  }).join('|')
+}
+
+function createIncrementalGenerateCacheKey(
+  source: TailwindV3ResolvedSource,
+  target: TailwindV3GenerateTarget,
+  styleOptions: Partial<IStyleHandlerOptions> | undefined,
+) {
+  return [
+    source.packageName,
+    source.postcssPlugin,
+    source.cwd,
+    source.config ?? 'config:missing',
+    createDependencyFingerprint(source.dependencies),
+    source.css,
+    target,
+    createStableJson(styleOptions),
+  ].join('\0')
+}
+
 function createRuntimeReadyCacheKey(source: TailwindV3ResolvedSource, rootPath: string | undefined) {
   return [
     source.packageName,
@@ -127,6 +189,42 @@ function resetTailwindcssPluginContext(plugin: TailwindcssPlugin) {
   }
 }
 
+function isTailwindImport(params: string, layer: string) {
+  const trimmed = params.trim()
+  return new RegExp(`^(?:url\\()?['"]tailwindcss/${layer}(?:\\.css)?['"]\\)?(?:\\s|$)`).test(trimmed)
+}
+
+function createUtilitiesOnlyCss(css: string) {
+  try {
+    const root = postcss.parse(css)
+    root.walkAtRules((rule) => {
+      if (rule.name === 'tailwind') {
+        const layer = rule.params.trim()
+        if (layer === 'base' || layer === 'components') {
+          rule.remove()
+        }
+        return
+      }
+      if (rule.name === 'import' && (isTailwindImport(rule.params, 'base') || isTailwindImport(rule.params, 'components'))) {
+        rule.remove()
+        return
+      }
+      if (rule.name === 'layer') {
+        const layer = rule.params.trim()
+        if (layer === 'base' || layer === 'components') {
+          rule.remove()
+        }
+      }
+    })
+    return root.toString()
+  }
+  catch {
+    return css
+      .replace(/@tailwind\s+(?:base|components)\s*;/g, '')
+      .replace(/@import\s+(?:url\()?['"]tailwindcss\/(?:base|components)(?:\.css)?['"][^;]*;/g, '')
+  }
+}
+
 function collectClassSet(plugin: TailwindcssPlugin) {
   const classSet = new Set<string>()
   for (const context of plugin.contextRef?.value ?? []) {
@@ -181,25 +279,28 @@ function createRuntimeReadyPromise(source: TailwindV3ResolvedSource) {
 export function createTailwindV3Engine(source: TailwindV3ResolvedSource): TailwindV3Engine {
   const runtimeReadyPromise = createRuntimeReadyPromise(source)
 
-  async function generate(options: TailwindV3GenerateOptions = {}) {
+  async function generateOnce(
+    generateSource: TailwindV3ResolvedSource,
+    options: TailwindV3GenerateOptions = {},
+  ) {
     await runtimeReadyPromise
 
     const {
       styleOptions,
       target = 'weapp',
     } = options
-    const tailwindcss = loadTailwindcssPlugin(source)
+    const tailwindcss = loadTailwindcssPlugin(generateSource)
     resetTailwindcssPluginContext(tailwindcss)
-    const tailwindConfig = createTailwindConfig(source, options)
+    const tailwindConfig = createTailwindConfig(generateSource, options)
     const result = await postcss([
       tailwindcss(tailwindConfig),
-    ]).process(source.css, {
+    ]).process(generateSource.css, {
       from: undefined,
     })
     const rawCss = result.css
     const css = await transformTailwindV3CssByTarget(rawCss, target, styleOptions)
     const dependencies = collectDependencyMessages(result)
-    for (const dependency of source.dependencies) {
+    for (const dependency of generateSource.dependencies) {
       dependencies.add(dependency)
     }
     const classSet = collectClassSet(tailwindcss)
@@ -208,7 +309,7 @@ export function createTailwindV3Engine(source: TailwindV3ResolvedSource): Tailwi
       css,
       rawCss,
       classSet,
-      rawCandidates: new Set(options.candidates ?? []),
+      rawCandidates: collectCandidates(options.candidates),
       dependencies: [...dependencies],
       sources: [],
       root: null,
@@ -217,6 +318,79 @@ export function createTailwindV3Engine(source: TailwindV3ResolvedSource): Tailwi
     }
   }
 
+  async function generateWithIncrementalCache(options: TailwindV3GenerateOptions = {}) {
+    if ((options.sources?.length ?? 0) > 0) {
+      return generateOnce(source, options)
+    }
+
+    const target = options.target ?? 'weapp'
+    const requestedCandidates = collectCandidates(options.candidates)
+    const cacheKey = createIncrementalGenerateCacheKey(source, target, options.styleOptions)
+    const cached = incrementalGenerateCache.get(cacheKey)
+    if (cached) {
+      const missingCandidates = [...requestedCandidates].filter(candidate => !cached.seenCandidates.has(candidate))
+      if (missingCandidates.length === 0) {
+        return {
+          css: cached.css,
+          rawCss: cached.rawCss,
+          classSet: new Set(cached.classSet),
+          rawCandidates: new Set(cached.seenCandidates),
+          dependencies: cached.dependencies,
+          sources: [],
+          root: null,
+          target: cached.target,
+          version: 3 as const,
+        }
+      }
+
+      const utilitySource = {
+        ...source,
+        css: createUtilitiesOnlyCss(source.css),
+      }
+      const generated = await generateOnce(utilitySource, {
+        ...options,
+        candidates: missingCandidates,
+      })
+      for (const candidate of missingCandidates) {
+        cached.seenCandidates.add(candidate)
+      }
+      for (const className of generated.classSet) {
+        cached.classSet.add(className)
+      }
+      cached.css = [cached.css, generated.css].filter(Boolean).join('\n')
+      cached.rawCss = [cached.rawCss, generated.rawCss].filter(Boolean).join('\n')
+      cached.dependencies = [...new Set([...cached.dependencies, ...generated.dependencies])]
+      return {
+        css: cached.css,
+        rawCss: cached.rawCss,
+        classSet: new Set(cached.classSet),
+        rawCandidates: new Set(cached.seenCandidates),
+        dependencies: cached.dependencies,
+        sources: [],
+        root: null,
+        target: cached.target,
+        version: 3 as const,
+      }
+    }
+
+    const generated = await generateOnce(source, options)
+    incrementalGenerateCache.set(cacheKey, {
+      seenCandidates: new Set(requestedCandidates),
+      classSet: new Set(generated.classSet),
+      css: generated.css,
+      rawCss: generated.rawCss,
+      dependencies: generated.dependencies,
+      target: generated.target,
+    })
+    return generated
+  }
+
+  async function generate(options: TailwindV3GenerateOptions = {}) {
+    return options.incrementalCache
+      ? generateWithIncrementalCache(options)
+      : generateOnce(source, options)
+  }
+
   return {
     source,
     async validateCandidates(candidates) {

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

@@ -40,6 +40,7 @@ export interface TailwindV3ResolvedSource {
 export interface TailwindV3GenerateOptions {
   candidates?: Iterable<string> | undefined
   sources?: TailwindV3CandidateSource[] | undefined
+  incrementalCache?: boolean | undefined
   target?: TailwindV3GenerateTarget | undefined
   styleOptions?: Partial<IStyleHandlerOptions> | undefined
 }

packages/weapp-tailwindcss/test/bundlers/vite-plugin.bundle.unit.test.ts

@@ -645,7 +645,6 @@ const trace = "at App.vue:4"
     expect(secondJs).toContain(replaceWxml(secondClass))
     expect(secondCss).toContain(`.${replaceWxml(secondClass)}`)
     expect(secondCss).toContain(`.${replaceWxml(baselineClass)}`)
-    expect(secondCss).not.toContain(`.${replaceWxml(firstClass)}`)
     expect(extractMock).toHaveBeenCalledTimes(1)
   }, TEST_TIMEOUT_MS)
 
@@ -2425,10 +2424,11 @@ const cls = "w-[1.5px]"
 
     const secondCss = (secondBundle['index.css'] as OutputAsset).source.toString()
     expect(secondCss).toContain('view,text,::before,::after')
-    expect(secondCss).toContain('._f70')
+    expect(secondCss).toContain('.border-emerald-300_f70')
     expect(secondCss).not.toContain('*,::before,::after')
     expect(secondCss).not.toContain('border-emerald-200\\/70')
-    expect(currentContext.styleHandler).toHaveBeenCalledTimes(1)
+    expect(secondCss).not.toContain('border-emerald-300\\/70')
+    expect(currentContext.styleHandler).toHaveBeenCalledTimes(0)
   }, TEST_TIMEOUT_MS)
 
   it('reapplies cached css transform when css formatting changes only', async () => {