feat(tailwindcss-patch): expose tailwind v4 engine api

Author: sonofmagic

.changeset/tall-masks-breathe.md

@@ -0,0 +1,5 @@
+---
+"tailwindcss-patch": minor
+---
+
+Expose a reusable Tailwind CSS v4 engine API for resolving CSS sources, validating candidates through the v4 design system, and generating CSS with Tailwind's compile/build pipeline.

packages/tailwindcss-patch/src/extraction/candidate-extractor.ts

@@ -8,78 +8,21 @@ import type {
 import { promises as fs } from 'node:fs'
 import process from 'node:process'
 import path from 'pathe'
+import { resolveValidTailwindV4Candidates } from '../v4/candidates'
+import { getTailwindV4DesignSystemCacheKey, loadTailwindV4DesignSystem } from '../v4/node-adapter'
 
-let nodeImportPromise: ReturnType<typeof importNode> | undefined
 let oxideImportPromise: ReturnType<typeof importOxide> | undefined
-const designSystemPromiseCache = new Map<string, Promise<any>>()
 const designSystemCandidateCache = new Map<string, Map<string, boolean>>()
 
-async function importNode() {
-  return import('@tailwindcss/node')
-}
-
 async function importOxide() {
   return import('@tailwindcss/oxide')
 }
 
-function getNodeModule() {
-  nodeImportPromise ??= importNode()
-  return nodeImportPromise
-}
-
 function getOxideModule() {
   oxideImportPromise ??= importOxide()
   return oxideImportPromise
 }
 
-function createDesignSystemCacheKey(css: string, bases: string[]) {
-  return JSON.stringify({
-    css,
-    bases: Array.from(new Set(bases.filter(Boolean))),
-  })
-}
-
-async function loadDesignSystem(css: string, bases: string[]) {
-  const uniqueBases = Array.from(new Set(bases.filter(Boolean)))
-  if (uniqueBases.length === 0) {
-    throw new Error('No base directories provided for Tailwind CSS design system.')
-  }
-
-  const cacheKey = createDesignSystemCacheKey(css, uniqueBases)
-  const cached = designSystemPromiseCache.get(cacheKey)
-  if (cached) {
-    return cached
-  }
-
-  const promise = (async () => {
-    const { __unstable__loadDesignSystem } = await getNodeModule()
-    let lastError: unknown
-
-    for (const base of uniqueBases) {
-      try {
-        return await __unstable__loadDesignSystem(css, { base })
-      }
-      catch (error) {
-        lastError = error
-      }
-    }
-
-    if (lastError instanceof Error) {
-      throw lastError
-    }
-    throw new Error('Failed to load Tailwind CSS design system.')
-  })()
-
-  designSystemPromiseCache.set(cacheKey, promise)
-  promise.catch(() => {
-    if (designSystemPromiseCache.get(cacheKey) === promise) {
-      designSystemPromiseCache.delete(cacheKey)
-      designSystemCandidateCache.delete(cacheKey)
-    }
-  })
-  return promise
-}
-
 export interface ExtractValidCandidatesOption {
   sources?: SourceEntry[]
   base?: string
@@ -131,8 +74,15 @@ export async function extractValidCandidates(options?: ExtractValidCandidatesOpt
     negated: source.negated,
   }))
 
-  const designSystemKey = createDesignSystemCacheKey(css, [base, ...baseFallbacks])
-  const designSystem = await loadDesignSystem(css, [base, ...baseFallbacks])
+  const source = {
+    projectRoot: defaultCwd,
+    base,
+    baseFallbacks,
+    css,
+    dependencies: [],
+  }
+  const designSystemKey = getTailwindV4DesignSystemCacheKey(source)
+  const designSystem = await loadTailwindV4DesignSystem(source)
   const candidateCache = designSystemCandidateCache.get(designSystemKey) ?? new Map<string, boolean>()
   designSystemCandidateCache.set(designSystemKey, candidateCache)
 
@@ -163,15 +113,10 @@ export async function extractValidCandidates(options?: ExtractValidCandidatesOpt
     return validCandidates
   }
 
-  const cssByCandidate = designSystem.candidatesToCss(uncachedCandidates)
+  const validUncachedCandidates = resolveValidTailwindV4Candidates(designSystem, uncachedCandidates)
 
-  for (let index = 0; index < uncachedCandidates.length; index++) {
-    const candidate = uncachedCandidates[index]
-    if (candidate === undefined) {
-      continue
-    }
-    const candidateCss = cssByCandidate[index]
-    const isValid = typeof candidateCss === 'string' && candidateCss.trim().length > 0
+  for (const candidate of uncachedCandidates) {
+    const isValid = validUncachedCandidates.has(candidate)
     candidateCache.set(candidate, isValid)
     if (!isValid) {
       continue

packages/tailwindcss-patch/src/index.bundle.ts

@@ -33,6 +33,13 @@ import {
   runTailwindBuild,
 } from './install'
 import logger from './logger'
+import {
+  createTailwindV4Engine,
+  loadTailwindV4DesignSystem,
+  resolveTailwindV4Source,
+  resolveTailwindV4SourceFromPatchOptions,
+  resolveValidTailwindV4Candidates,
+} from './v4'
 
 const require = createRequire(import.meta.url)
 
@@ -46,18 +53,23 @@ export {
   CacheStore,
   collectClassesFromContexts,
   collectClassesFromTailwindV4,
+  createTailwindV4Engine,
   extractProjectCandidatesWithPositions,
   extractRawCandidates,
   extractRawCandidatesWithPositions,
   extractValidCandidates,
   getPatchStatusReport,
   groupTokensByFile,
   loadRuntimeContexts,
+  loadTailwindV4DesignSystem,
   logger,
   migrateConfigFiles,
   MIGRATION_REPORT_KIND,
   MIGRATION_REPORT_SCHEMA_VERSION,
   normalizeOptions,
+  resolveTailwindV4Source,
+  resolveTailwindV4SourceFromPatchOptions,
+  resolveValidTailwindV4Candidates,
   restoreConfigFiles,
   runTailwindBuild,
   tailwindcssPatchCommands,
@@ -91,6 +103,15 @@ export type {
 } from './commands/validate'
 export type { TailwindCssPatchOptions } from './config'
 export * from './types'
+export type {
+  TailwindV4CandidateSource,
+  TailwindV4DesignSystem,
+  TailwindV4Engine,
+  TailwindV4GenerateOptions,
+  TailwindV4GenerateResult,
+  TailwindV4ResolvedSource,
+  TailwindV4SourceOptions,
+} from './v4'
 
 export function mountTailwindcssPatchCommands(cli: CAC, options: TailwindcssPatchCliMountOptions = {}) {
   return loadCliModule().mountTailwindcssPatchCommands(cli, options)

packages/tailwindcss-patch/src/index.ts

@@ -51,6 +51,22 @@ export {
 } from './install'
 export { default as logger } from './logger'
 export * from './types'
+export {
+  createTailwindV4Engine,
+  loadTailwindV4DesignSystem,
+  resolveTailwindV4Source,
+  resolveTailwindV4SourceFromPatchOptions,
+  resolveValidTailwindV4Candidates,
+} from './v4'
+export type {
+  TailwindV4CandidateSource,
+  TailwindV4DesignSystem,
+  TailwindV4Engine,
+  TailwindV4GenerateOptions,
+  TailwindV4GenerateResult,
+  TailwindV4ResolvedSource,
+  TailwindV4SourceOptions,
+} from './v4'
 
 export function defineConfig<T extends TailwindcssMangleConfig>(config: T): T {
   return config