perf: reuse v3 hmr generation context

Author: sonofmagic

.changeset/v3-hmr-context-cache.md

@@ -0,0 +1,5 @@
+---
+"weapp-tailwindcss": patch
+---
+
+优化 Tailwind CSS v3 开发热更新性能，增量生成时复用 Tailwind v3 runtime context，并缓存稳定 CSS 源的 legacy compat 转换结果，避免新增 class 时重复重建 v3 上下文和重复转换兼容 CSS。

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

@@ -40,6 +40,40 @@ const LEGACY_CONTAINER_COMPAT_CSS = [
   '}',
 ].join('\n')
 
+const LEGACY_COMPAT_CACHE_LIMIT = 128
+const legacyCompatSourceCache = new Map<string, string>()
+const legacyCompatTransformCache = new Map<string, string>()
+
+function setLimitedCacheValue(cache: Map<string, string>, key: string, value: string) {
+  if (cache.size >= LEGACY_COMPAT_CACHE_LIMIT) {
+    const firstKey = cache.keys().next().value
+    if (firstKey !== undefined) {
+      cache.delete(firstKey)
+    }
+  }
+  cache.set(key, value)
+}
+
+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 createLegacyCompatTransformCacheKey(source: string, options: IStyleHandlerOptions) {
+  return `${createStableJson(options)}\0${source}`
+}
+
 export function removeTailwindApplyRules(rawSource: string) {
   try {
     const root = postcss.parse(rawSource)
@@ -67,8 +101,14 @@ export function removeTailwindApplyRules(rawSource: string) {
 }
 
 function resolveLegacyCompatCssSource(rawSource: string) {
+  const cached = legacyCompatSourceCache.get(rawSource)
+  if (cached !== undefined) {
+    return cached
+  }
   const source = removeTailwindSourceDirectives(stripTailwindBanners(rawSource))
-  return removeUnsupportedMiniProgramAtRules(removeTailwindApplyRules(source))
+  const resolved = removeUnsupportedMiniProgramAtRules(removeTailwindApplyRules(source))
+  setLimitedCacheValue(legacyCompatSourceCache, rawSource, resolved)
+  return resolved
 }
 
 function hasContainerConfigToken(rawSource: string) {
@@ -145,10 +185,17 @@ export async function appendLegacyCompatCss(
     return createCssAppend(css, compatSource)
   }
 
-  const { css: compatCss } = await styleHandler(compatSource, {
+  const styleOptions = {
     ...cssHandlerOptions,
     ...generatorStyleOptions,
-  })
+  }
+  const compatCssCacheKey = createLegacyCompatTransformCacheKey(compatSource, styleOptions)
+  let compatCss = legacyCompatTransformCache.get(compatCssCacheKey)
+  if (compatCss === undefined) {
+    const handled = await styleHandler(compatSource, styleOptions)
+    compatCss = handled.css
+    setLimitedCacheValue(legacyCompatTransformCache, compatCssCacheKey, compatCss)
+  }
   const cleanedCompatCss = collectDedupedPostTransformCompatCss(
     removeDuplicatedViteMarkers(removeUnsupportedMiniProgramAtRules(compatCss), css),
     css,
@@ -183,10 +230,17 @@ export async function appendLegacyContainerCompatCss(
     return css
   }
 
-  const { css: compatCss } = await styleHandler(LEGACY_CONTAINER_COMPAT_CSS, {
+  const styleOptions = {
     ...cssHandlerOptions,
     ...generatorStyleOptions,
-  })
+  }
+  const compatCssCacheKey = createLegacyCompatTransformCacheKey(LEGACY_CONTAINER_COMPAT_CSS, styleOptions)
+  let compatCss = legacyCompatTransformCache.get(compatCssCacheKey)
+  if (compatCss === undefined) {
+    const handled = await styleHandler(LEGACY_CONTAINER_COMPAT_CSS, styleOptions)
+    compatCss = handled.css
+    setLimitedCacheValue(legacyCompatTransformCache, compatCssCacheKey, compatCss)
+  }
   const cleanedCompatCss = collectDedupedPostTransformCompatCss(
     removeUnsupportedMiniProgramAtRules(compatCss),
     css,

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

@@ -44,6 +44,7 @@ interface TailwindV3Internals {
 }
 
 interface TailwindV3IncrementalGenerateCacheEntry {
+  context: TailwindV3Context
   seenCandidates: Set<string>
   classSet: Set<string>
   css: string
@@ -234,42 +235,6 @@ function createRuntimeReadyCacheKey(source: TailwindV3ResolvedSource, rootPath:
   ].join('\0')
 }
 
-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 isDirectUtilitiesOnlyCss(css: string) {
   return css.replace(/\s+/g, '') === '@tailwindutilities;'
 }
@@ -304,8 +269,8 @@ function sortCandidates(candidates: Iterable<string>) {
   })
 }
 
-function appendDirectUtilityRules(root: postcss.Root, context: TailwindV3Context) {
-  const sortedRules = context.offsets.sort([...context.ruleCache])
+function appendUtilityRules(root: postcss.Root, context: TailwindV3Context, rules: Array<[unknown, postcss.Node]>) {
+  const sortedRules = context.offsets.sort(rules)
   for (const [sort, rule] of sortedRules) {
     const tailwindRaw = rule.raws.tailwind as { parentLayer?: string } | undefined
     if (sort.layer === 'utilities' || (sort.layer === 'variants' && tailwindRaw?.parentLayer === 'utilities')) {
@@ -314,6 +279,10 @@ function appendDirectUtilityRules(root: postcss.Root, context: TailwindV3Context
   }
 }
 
+function appendDirectUtilityRules(root: postcss.Root, context: TailwindV3Context) {
+  appendUtilityRules(root, context, [...context.ruleCache])
+}
+
 function createRuntimeReadyPromise(source: TailwindV3ResolvedSource) {
   const patcher = createTailwindcssPatcher({
     basedir: source.cwd,
@@ -397,6 +366,7 @@ export function createTailwindV3Engine(source: TailwindV3ResolvedSource): Tailwi
     return {
       css,
       rawCss,
+      context,
       classSet,
       rawCandidates: collectCandidates(options.candidates),
       dependencies: [...dependencies],
@@ -407,6 +377,35 @@ export function createTailwindV3Engine(source: TailwindV3ResolvedSource): Tailwi
     }
   }
 
+  async function generateIncrementalMissingUtilities(
+    context: TailwindV3Context,
+    candidates: string[],
+    target: TailwindV3GenerateTarget,
+    styleOptions: Partial<IStyleHandlerOptions> | undefined,
+  ) {
+    tailwindInternals ??= loadTailwindV3Internals(source)
+    const internals = tailwindInternals
+    const root = postcss.root()
+    const result: TailwindV3ProcessResult = {
+      css: '',
+      messages: [],
+    }
+    const rules = internals.generateRules(new Set(sortCandidates(candidates)), context)
+    appendUtilityRules(root, context, rules)
+    internals.resolveDefaultsAtRules(context)(root, result)
+    internals.collapseAdjacentRules(context)(root, result)
+    internals.collapseDuplicateDeclarations(context)(root, result)
+
+    const rawCss = root.toString()
+    const css = await transformTailwindV3CssByTarget(rawCss, target, styleOptions)
+    return {
+      css,
+      rawCss,
+      classSet: collectClassSet(context),
+      dependencies: collectDependencyMessages(result),
+    }
+  }
+
   async function generateWithIncrementalCache(options: TailwindV3GenerateOptions = {}) {
     if ((options.sources?.length ?? 0) > 0) {
       return generateOnce(source, options)
@@ -432,14 +431,12 @@ export function createTailwindV3Engine(source: TailwindV3ResolvedSource): Tailwi
         }
       }
 
-      const utilitySource = {
-        ...source,
-        css: createUtilitiesOnlyCss(source.css),
-      }
-      const generated = await generateOnce(utilitySource, {
-        ...options,
-        candidates: missingCandidates,
-      })
+      const generated = await generateIncrementalMissingUtilities(
+        cached.context,
+        missingCandidates,
+        target,
+        options.styleOptions,
+      )
       for (const candidate of missingCandidates) {
         cached.seenCandidates.add(candidate)
       }
@@ -464,6 +461,7 @@ export function createTailwindV3Engine(source: TailwindV3ResolvedSource): Tailwi
 
     const generated = await generateOnce(source, options)
     incrementalGenerateCache.set(cacheKey, {
+      context: generated.context,
       seenCandidates: new Set(requestedCandidates),
       classSet: new Set(generated.classSet),
       css: generated.css,

packages/weapp-tailwindcss/test/bundlers/generator-css.unit.test.ts

@@ -224,6 +224,75 @@ describe('bundlers/shared generator css', () => {
     }))
   })
 
+  it('reuses transformed legacy compat css for stable source during hmr', async () => {
+    const firstRuntimeSet = new Set(['bg-blue-500'])
+    const secondRuntimeSet = new Set(['bg-red-500'])
+    const rawSource = '@import "tailwindcss";\n.card{color:red}'
+    const generateMock = vi.fn(async (options: any) => {
+      const candidate = [...options.candidates][0]
+      return {
+        css: `.${candidate}{background-color:red}`,
+        rawCss: `.${candidate}{background-color:red}`,
+        target: 'weapp',
+        classSet: options.candidates,
+        dependencies: [],
+        sources: [],
+        root: null,
+      }
+    })
+
+    vi.doMock('@/generator', () => ({
+      ...createDefaultGeneratorMock(),
+      createWeappTailwindcssGenerator: vi.fn(() => ({
+        generate: generateMock,
+      })),
+    }))
+
+    const { generateCssByGenerator } = await import('@/bundlers/shared/generator-css')
+    const styleHandler = vi.fn(async (code: string) => ({ css: `legacy:${code}` }))
+    const baseOptions = {
+      opts: {
+        styleHandler,
+      } as any,
+      runtimeState: {
+        twPatcher: {
+          majorVersion: 4,
+        } as any,
+        readyPromise: Promise.resolve(),
+      },
+      rawSource,
+      file: 'app.wxss',
+      cssHandlerOptions: {
+        isMainChunk: true,
+        postcssOptions: {
+          options: {
+            from: 'app.wxss',
+          },
+        },
+        majorVersion: 4,
+      } as any,
+      cssUserHandlerOptions: {
+        isMainChunk: false,
+        majorVersion: 4,
+      } as any,
+      styleHandler,
+      debug: vi.fn(),
+    }
+
+    const first = await generateCssByGenerator({
+      ...baseOptions,
+      runtime: firstRuntimeSet,
+    })
+    const second = await generateCssByGenerator({
+      ...baseOptions,
+      runtime: secondRuntimeSet,
+    })
+
+    expect(first?.css).toContain('legacy:.card{color:red}')
+    expect(second?.css).toContain('legacy:.card{color:red}')
+    expect(styleHandler).toHaveBeenCalledTimes(1)
+  })
+
   it('treats weapp-tailwindcss imports as Tailwind v4 source entries by default', async () => {
     const runtimeSet = new Set(['w-[100px]'])
     const rawSource = '@import "weapp-tailwindcss";\n.card{color:red}'