perf: warm tailwind v4 incremental cache

Author: sonofmagic

.changeset/warm-v4-incremental-cache.md

@@ -0,0 +1,5 @@
+---
+"weapp-tailwindcss": patch
+---
+
+Tailwind CSS v4 初始源码扫描生成完成后会同步预热增量生成缓存，避免第一次热更新因为没有基线缓存而再次触发完整 v4 生成。

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

@@ -36,6 +36,15 @@ interface TailwindV4IncrementalGenerateCacheEntry {
   target: TailwindV4GenerateTarget
 }
 
+interface TailwindV4IncrementalCacheSeedOptions {
+  compatibleSource: TailwindV4ResolvedSource
+  generated: Awaited<ReturnType<TailwindV4Engine['generate']>>
+  requestedCandidates: Set<string>
+  styleOptions: Partial<IStyleHandlerOptions> | undefined
+  tailwindcssV3Compatibility: boolean | undefined
+  target: TailwindV4GenerateTarget
+}
+
 function findLeadingImportInsertionIndex(css: string) {
   const importPattern = /(?:^|\n)\s*@import\b[^;]*;/g
   let insertionIndex = 0
@@ -134,6 +143,36 @@ function resolveTargetCandidates(
     : collected
 }
 
+function collectSeenCandidates(
+  generated: Pick<Awaited<ReturnType<TailwindV4Engine['generate']>>, 'rawCandidates' | 'classSet'>,
+  requestedCandidates: Set<string>,
+) {
+  return new Set([
+    ...requestedCandidates,
+    ...generated.rawCandidates,
+    ...generated.classSet,
+  ])
+}
+
+function seedIncrementalGenerateCache(options: TailwindV4IncrementalCacheSeedOptions) {
+  const cacheKey = createIncrementalGenerateCacheKey(
+    options.compatibleSource,
+    options.target,
+    options.styleOptions,
+    options.tailwindcssV3Compatibility,
+  )
+  incrementalGenerateCache.set(cacheKey, {
+    seenCandidates: collectSeenCandidates(options.generated, options.requestedCandidates),
+    classSet: new Set(options.generated.classSet),
+    css: options.generated.css,
+    rawCss: options.generated.rawCss,
+    dependencies: options.generated.dependencies,
+    sources: options.generated.sources,
+    root: options.generated.root,
+    target: options.generated.target,
+  })
+}
+
 function parseImportSourceParam(params: string) {
   const match = /\bsource\(\s*(none|(['"])(.*?)\2)\s*\)/.exec(params)
   if (!match) {
@@ -360,13 +399,27 @@ export function createTailwindV4Engine(source: TailwindV4ResolvedSource): Tailwi
   }
 
   async function generateWithIncrementalCache(options: TailwindV4GenerateOptions = {}) {
-    if ((options.sources?.length ?? 0) > 0 || options.bareArbitraryValues !== undefined || options.scanSources === true || Array.isArray(options.scanSources)) {
-      return generateOnce(source, options)
-    }
-
     const target = options.target ?? 'weapp'
     const compatibleSource = createCompatibleSource(source, target, options.tailwindcssV3Compatibility)
     const requestedCandidates = resolveTargetCandidates(options.candidates, target)
+
+    if ((options.sources?.length ?? 0) > 0 || options.bareArbitraryValues !== undefined || Array.isArray(options.scanSources)) {
+      return generateOnce(source, options)
+    }
+
+    if (options.scanSources === true) {
+      const generated = await generateOnce(source, options)
+      seedIncrementalGenerateCache({
+        compatibleSource,
+        generated,
+        requestedCandidates,
+        styleOptions: options.styleOptions,
+        tailwindcssV3Compatibility: options.tailwindcssV3Compatibility,
+        target,
+      })
+      return generated
+    }
+
     const cacheKey = createIncrementalGenerateCacheKey(
       compatibleSource,
       target,
@@ -427,15 +480,13 @@ export function createTailwindV4Engine(source: TailwindV4ResolvedSource): Tailwi
     }
 
     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,
-      sources: generated.sources,
-      root: generated.root,
-      target: generated.target,
+    seedIncrementalGenerateCache({
+      compatibleSource,
+      generated,
+      requestedCandidates,
+      styleOptions: options.styleOptions,
+      tailwindcssV3Compatibility: options.tailwindcssV3Compatibility,
+      target,
     })
     return generated
   }

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

@@ -110,6 +110,37 @@ describe('tailwindcss v4 engine', () => {
     expect(second.css.match(/\.text-_b88rpx_B/g) ?? []).toHaveLength(1)
   })
 
+  it('seeds the v4 incremental cache from the initial source scan', async () => {
+    const source = await resolveTailwindV4Source({
+      css: MINIMAL_THEME_CSS,
+      base: process.cwd(),
+    })
+    const engine = createTailwindV4Engine(source)
+
+    const first = await engine.generate({
+      candidates: ['text-[88rpx]'],
+      incrementalCache: true,
+      scanSources: true,
+      styleOptions: {
+        isMainChunk: false,
+      },
+    })
+    const second = await engine.generate({
+      candidates: ['text-[88rpx]', 'text-[188rpx]'],
+      incrementalCache: true,
+      scanSources: false,
+      styleOptions: {
+        isMainChunk: false,
+      },
+    })
+
+    expect(first.classSet).toEqual(new Set(['text-[88rpx]']))
+    expect(second.classSet).toEqual(new Set(['text-[88rpx]', 'text-[188rpx]']))
+    expect(second.css).toContain('.text-_b88rpx_B')
+    expect(second.css).toContain('.text-_b188rpx_B')
+    expect(second.css.match(/\.text-_b88rpx_B/g) ?? []).toHaveLength(1)
+  })
+
   it('uses mini-program-safe Tailwind v4 default color variables for native v4 weapp output', async () => {
     const source = await resolveTailwindV4Source({
       css: `