fix: stabilize source scanning watch hmr

Author: sonofmagic

demo/taro-webpack-vue3-tailwindcss-v3/src/pages/index/index.vue

@@ -26,3 +26,21 @@ const dynamicClass = computed(() => 'bg-[#123456] text-[#ffffff] p-[20px]')
 
 useLoad(() => {})
 </script>
+
+<style lang="scss">
+.test {
+  @apply flex items-center justify-center h-[100px] w-[100px] rounded-[40px] bg-[#123456] bg-opacity-[0.54] text-[#ffffff] #{!important};
+}
+
+.aspect-w-16 > * {
+  color: red;
+}
+
+.a {
+  color: green;
+}
+
+.b {
+  color: yellow;
+}
+</style>

demo/taro-webpack-vue3-tailwindcss-v4/src/pages/index/index.css

@@ -1,3 +1,5 @@
+@reference "tailwindcss";
+
 .tw-page-style-watch-anchor {
   color: inherit;
 }

demo/taro-webpack-vue3-tailwindcss-v4/src/pages/index/index.vue

@@ -13,6 +13,7 @@
 
 <script setup lang="ts">
 import { useLoad } from '@tarojs/taro'
+import './index.css'
 
 useLoad(() => {})
 </script>

packages/weapp-tailwindcss/src/bundlers/vite/index.ts

@@ -24,7 +24,7 @@ import { resolveImplicitAppTypeFromViteRoot } from './resolve-app-type'
 import { createRewriteCssImportsPlugins } from './rewrite-css-imports'
 import { createViteRuntimeClassSet } from './runtime-class-set'
 import { createSourceCandidateCollector, isSourceCandidateRequest } from './source-candidates'
-import { createViteSourceScanMatcher, resolveViteSourceScanEntries } from './source-scan'
+import { createViteSourceScanMatcher, resolveViteSourceScanEntries, resolveViteTailwindV4CssDependencies } from './source-scan'
 import { resolveImplicitTailwindcssBasedirFromViteRoot } from './tailwind-basedir'
 import { cleanUrl, slash } from './utils'
 
@@ -130,9 +130,11 @@ export function WeappTailwindcss(options: UserDefinedOptions = {}): Plugin[] | u
       return
     }
     autoCssSourceContent.set(sourceFile, css)
+    const dependencies = await resolveViteTailwindV4CssDependencies(css, path.dirname(sourceFile))
     upsertTailwindV4CssSource(opts, {
       file: sourceFile,
       css,
+      dependencies,
     })
     debug('detected tailwindcss v4 css source from vite css module: %s', sourceFile)
     autoCssSourcesRefresh = (autoCssSourcesRefresh ?? Promise.resolve()).then(async () => {

packages/weapp-tailwindcss/src/bundlers/vite/source-scan.ts

@@ -5,10 +5,12 @@ import path from 'node:path'
 import process from 'node:process'
 import micromatch from 'micromatch'
 import postcss from 'postcss'
+import { loadConfig } from 'tailwindcss-config'
 import {
   collectCssInlineSourceCandidates,
   createSourceScanPattern,
   normalizeLegacyContentEntries,
+  parseConfigParam,
   resolveCssSourceEntries,
 } from '@/tailwindcss/source-scan'
 import { resolveTailwindV3SourceFromPatcher } from '@/tailwindcss/v3-engine'
@@ -72,17 +74,51 @@ function resolveSourceBase(base: string, sourcePath: string) {
   return path.isAbsolute(sourcePath) ? sourcePath : path.resolve(base, sourcePath)
 }
 
+function resolveConfigPath(base: string, configPath: string) {
+  return path.isAbsolute(configPath) ? path.resolve(configPath) : path.resolve(base, configPath)
+}
+
 interface ResolvedTailwindV4CssEntries {
   entries: TailwindSourceEntry[]
   explicit: boolean
   inlineCandidates: TailwindInlineSourceCandidates
+  dependencies: string[]
 }
 
 export interface ResolvedViteSourceScan {
   entries?: TailwindSourceEntry[]
   inlineCandidates?: TailwindInlineSourceCandidates
 }
 
+async function resolveConfigContentEntries(root: postcss.Root, base: string) {
+  const configPaths = new Set<string>()
+  root.walkAtRules('config', (rule) => {
+    const configPath = parseConfigParam(rule.params)
+    if (configPath) {
+      configPaths.add(resolveConfigPath(base, configPath))
+    }
+  })
+
+  const entries: TailwindSourceEntry[] = []
+  for (const configPath of configPaths) {
+    try {
+      const loaded = await loadConfig({
+        config: configPath,
+        cwd: path.dirname(configPath),
+      })
+      entries.push(...normalizeLegacyContentEntries(loaded?.config.content, path.dirname(configPath)))
+    }
+    catch {
+      // 依赖收集只负责补充 watch 签名，配置有效性由 Tailwind 生成阶段校验。
+    }
+  }
+
+  return {
+    dependencies: [...configPaths],
+    entries,
+  }
+}
+
 async function resolveTailwindV4EntriesFromCss(css: string, base: string): Promise<ResolvedTailwindV4CssEntries | undefined> {
   let root: postcss.Root
   try {
@@ -94,7 +130,14 @@ async function resolveTailwindV4EntriesFromCss(css: string, base: string): Promi
 
   let importSourceBase: string | undefined
   let hasSourceNone = false
-  const entries = await resolveCssSourceEntries(root, base, VITE_SOURCE_CANDIDATE_PATTERN)
+  const [sourceEntries, configEntries] = await Promise.all([
+    resolveCssSourceEntries(root, base, VITE_SOURCE_CANDIDATE_PATTERN),
+    resolveConfigContentEntries(root, base),
+  ])
+  const entries = [
+    ...configEntries.entries,
+    ...sourceEntries,
+  ]
   const inlineCandidates = collectCssInlineSourceCandidates(root)
 
   root.walkAtRules('import', (rule) => {
@@ -122,6 +165,7 @@ async function resolveTailwindV4EntriesFromCss(css: string, base: string): Promi
       ],
       explicit: true,
       inlineCandidates,
+      dependencies: configEntries.dependencies,
     }
   }
 
@@ -130,6 +174,7 @@ async function resolveTailwindV4EntriesFromCss(css: string, base: string): Promi
       entries,
       explicit: true,
       inlineCandidates,
+      dependencies: configEntries.dependencies,
     }
   }
 
@@ -138,16 +183,23 @@ async function resolveTailwindV4EntriesFromCss(css: string, base: string): Promi
         entries,
         explicit: true,
         inlineCandidates,
+        dependencies: configEntries.dependencies,
       }
     : inlineCandidates.included.size > 0 || inlineCandidates.excluded.size > 0
       ? {
           entries: [],
           explicit: true,
           inlineCandidates,
+          dependencies: configEntries.dependencies,
         }
       : undefined
 }
 
+export async function resolveViteTailwindV4CssDependencies(css: string, base: string) {
+  const resolved = await resolveTailwindV4EntriesFromCss(css, base)
+  return resolved?.dependencies ?? []
+}
+
 function collectExistingCssEntries(options: UserDefinedOptions) {
   return [
     ...(options.cssEntries ?? []),

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

@@ -1,7 +1,7 @@
 import type { OutputAsset, OutputChunk } from 'rollup'
 import type { Plugin, ResolvedConfig } from 'vite'
 import type { CreateJsHandlerOptions } from '@/types'
-import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
 import { MappingChars2String } from '@weapp-core/escape'
@@ -20,6 +20,12 @@ import {
 
 const TEST_TIMEOUT_MS = 30000
 const SPLIT_WHITESPACE_RE = /\s+/
+const MINIMAL_TAILWIND_V4_CSS = `
+@theme default {
+  --spacing: 0.25rem;
+}
+@tailwind utilities;
+`
 const createdDirs: string[] = []
 
 async function loadUnifiedVitePlugin() {
@@ -255,8 +261,13 @@ describe('bundlers/vite WeappTailwindcss bundle', () => {
   }, TEST_TIMEOUT_MS)
 
   it('detects tailwindcss v4 css sources from vite css transforms when omitted', async () => {
-    const entry = path.join(os.tmpdir(), 'weapp-tw-vite-auto-entry.css')
-    const css = '@import "tailwindcss";\n@plugin "./plugin.js";'
+    const root = await mkdtemp(path.join(os.tmpdir(), 'weapp-tw-vite-auto-entry-'))
+    createdDirs.push(root)
+    const entry = path.join(root, 'subpackage', 'entry.css')
+    const configFile = path.join(root, 'subpackage', 'tailwind.config.js')
+    const css = '@import "tailwindcss" source(none);\n@config "./tailwind.config.js";'
+    await mkdir(path.dirname(entry), { recursive: true })
+    await writeFile(configFile, 'module.exports = { content: ["./**/*.wxml"] }\n', 'utf8')
     const refreshTailwindcssPatcher = vi.fn()
     const context = createContext({
       twPatcher: {
@@ -287,12 +298,63 @@ describe('bundlers/vite WeappTailwindcss bundle', () => {
       {
         file: entry,
         css,
+        dependencies: [configFile],
       },
     ])
     expect(refreshTailwindcssPatcher).toHaveBeenCalledTimes(1)
     expect(String((result as any)?.code)).toContain('generator-placeholder.css')
   })
 
+  it('scans Tailwind v4 @config content for vite source candidates', async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), 'weapp-tw-vite-config-content-'))
+    createdDirs.push(root)
+    const cssEntry = path.join(root, 'sub-independent', 'pages', 'index.css')
+    const configFile = path.join(root, 'sub-independent', 'tailwind.config.cjs')
+    const pageFile = path.join(root, 'sub-independent', 'pages', 'index.wxml')
+    await mkdir(path.dirname(pageFile), { recursive: true })
+    await writeFile(configFile, 'module.exports = { content: ["./pages/**/*.{wxml,ts}"] }\n', 'utf8')
+    await writeFile(pageFile, '<view class="bg-[#010721] text-[35px] h-[29px]">ok</view>\n', 'utf8')
+
+    const context = createContext({
+      twPatcher: {
+        patch: vi.fn(),
+        getClassSet: vi.fn(async () => new Set()),
+        getClassSetSync: vi.fn(() => new Set()),
+        majorVersion: 4,
+        extract: vi.fn(async () => ({ classSet: new Set() })),
+      },
+    })
+    setCurrentContext(context)
+
+    const WeappTailwindcss = await loadUnifiedVitePlugin()
+    const plugins = WeappTailwindcss({
+      cssEntries: [cssEntry],
+    })
+    const sourcePlugin = plugins?.find(plugin => plugin.name === 'weapp-tailwindcss:adaptor:source-candidates') as Plugin
+    const postPlugin = plugins?.find(plugin => plugin.name === 'weapp-tailwindcss:adaptor:post') as Plugin
+    await writeFile(cssEntry, '@import "tailwindcss" source(none);\n@config "./tailwind.config.cjs";\n', 'utf8')
+    await (postPlugin.configResolved as any)?.call(postPlugin, {
+      command: 'build',
+      root,
+      css: { postcss: { plugins: [] } },
+      build: { outDir: 'dist' },
+    } as ResolvedConfig)
+    await (sourcePlugin.buildStart as any)?.call(sourcePlugin)
+
+    const bundle = {
+      'app.css': {
+        ...createRollupAsset(MINIMAL_TAILWIND_V4_CSS),
+        fileName: 'app.css',
+      },
+    }
+    const generateBundle = getGenerateBundleHandler(postPlugin)
+    await generateBundle?.call({ addWatchFile: vi.fn() }, {}, bundle, false)
+
+    expect(String(bundle['app.css'].source)).toContain('.bg-_b_h010721_B')
+    expect(String(bundle['app.css'].source)).toContain('.text-_b35px_B')
+    expect(String(bundle['app.css'].source)).toContain('.h-_b29px_B')
+  })
+
   it('updates auto tailwindcss v4 css source content on repeated vite css transforms', async () => {
     const entry = path.join(os.tmpdir(), 'weapp-tw-vite-auto-entry-update.css')
     const refreshTailwindcssPatcher = vi.fn()
@@ -321,6 +383,7 @@ describe('bundlers/vite WeappTailwindcss bundle', () => {
       {
         file: entry,
         css: '@import "tailwindcss";\n@source inline("h-4");',
+        dependencies: [],
       },
     ])
     expect(refreshTailwindcssPatcher).toHaveBeenCalledTimes(2)

packages/weapp-tailwindcss/test/watch-hmr-coverage-matrix.unit.test.ts

@@ -22,9 +22,12 @@ const styleApplyUnsupportedCases = new Set([
 
 const styleFunctionUnsupportedCases = new Set([
   'mpx-tailwindcss-v4',
+  'taro-vite-react-tailwindcss-v4',
+  'taro-webpack-react-tailwindcss-v4',
 ])
 
 const styleReferenceRequiredCases = new Set([
+  'gulp-tailwindcss-v4',
   'mpx-tailwindcss-v4',
   'uni-app-vite-tailwindcss-v4',
   'taro-vite-react-tailwindcss-v4',
@@ -91,7 +94,8 @@ describe('watch-hmr coverage matrix', () => {
         expect(subPackageMutation.templateMutation.verifyEscapedIn.length + (subPackageMutation.templateMutation.verifyClassLiteralIn?.length ?? 0)).toBeGreaterThan(0)
       }
       if (watchCase.contentMutation) {
-        expect(watchCase.contentMutation.verifyClassLiteralIn).toContain('js')
+        const expectedCarrier = watchCase.contentMutation.sourceFile.endsWith('.wxml') ? 'wxml' : 'js'
+        expect(watchCase.contentMutation.verifyClassLiteralIn).toContain(expectedCarrier)
       }
     }
   })
@@ -113,8 +117,9 @@ describe('watch-hmr coverage matrix', () => {
       }
 
       if (watchCase.contentMutation) {
+        const expectedCarrier = watchCase.contentMutation.sourceFile.endsWith('.wxml') ? 'wxml' : 'js'
         expectDemoSourceFile(watchCase.contentMutation.sourceFile, `${watchCase.project} content mutation`)
-        expect(watchCase.contentMutation.verifyClassLiteralIn, `${watchCase.project} content mutation should verify JS-visible literals`).toContain('js')
+        expect(watchCase.contentMutation.verifyClassLiteralIn, `${watchCase.project} content mutation should verify source-visible literals`).toContain(expectedCarrier)
       }
     }
   })
@@ -171,6 +176,14 @@ describe('watch-hmr coverage matrix', () => {
     expect(mpxCase?.minGlobalStyleEscapedClasses).toBeGreaterThanOrEqual(1)
   })
 
+  it('keeps Taro Webpack Vue3 v4 style HMR wired through the page css import', () => {
+    const watchCase = automatedWatchCases.find(item => item.project === 'demo/taro-webpack-vue3-tailwindcss-v4')
+
+    expect(watchCase).toBeDefined()
+    expect(watchCase?.styleMutation?.sourceFile).toBe('/repo/demo/taro-webpack-vue3-tailwindcss-v4/src/pages/index/index.css')
+    expect(watchCase?.outputStyleCandidates).toContain('/repo/demo/taro-webpack-vue3-tailwindcss-v4/dist/app.wxss')
+  })
+
   it('keeps the automated watch matrix explicit', () => {
     expect([...watchCoveredProjects].sort()).toEqual([...matrixProjects].sort())
   })