Improve utility lookup performance when using v4 (#1509)

Companion PR to tailwindlabs/tailwindcss#19405

The aim of this PR is to improve the performance around looking up /
compiling candidates into utilities when using v4.

It does this in three stages:

1. For earlier versions (v4.0–v4.1.17) we swap out PostCSS (mostly) with
our own CSS parser. The implementation is tailored to improve
performance and memory usage for how we use it. This also means I've
been able to optimize how we walk the AST and remove mutations in many
places.

There *are* still some internal APIs that use PostCSS because they
interface with multiple versions of Tailwind CSS. These still use
PostCSS and we translate our AST into a PostCSS AST for these cases.
Eventually these APIs will also be converted to use our internal CSS AST
directly — we'll support old versions by converting *from PostCSS* to
our internal AST — that is for a future PR.

2. For new enough versions, since our AST here mirrors the one in
Tailwind CSS, we can use the nodes directly from Tailwind CSS itself
instead of generating the code inside Tailwind CSS, serializing to a
string, and then finally re-parsing. This is exactly what the
`candidatesToAst` API enables (will ship in Tailwind CSS v4.1.18).

3. A large portion of the candidate compiling perf is spent on color
lookups. The above will help with that significantly but there's still a
large amount of time analyzing declaration values for colors. This PR
replaces our unwieldy color regex to pick out potential colors with a
fine tuned parser.

This speedup gives us a good bit more headroom for re-enabling mask
utility color swatches. The overhead from parsing an extra 5k utilities
is still too significant but it is now *much* lower than before. The
next big improvements will need to happen in core.

Author: thecrypticace

packages/tailwindcss-language-server/src/util/v4/design-system.ts

@@ -1,6 +1,5 @@
 import type { DesignSystem } from '@tailwindcss/language-service/src/util/v4'
 
-import postcss from 'postcss'
 import { createJiti } from 'jiti'
 import * as fs from 'node:fs/promises'
 import * as path from 'node:path'
@@ -10,6 +9,7 @@ import { pathToFileURL } from '../../utils'
 import type { Jiti } from 'jiti/lib/types'
 import { assets } from './assets'
 import { plugins } from './plugins'
+import { AstNode, cloneAstNode, parse } from '@tailwindcss/language-service/src/css'
 
 const HAS_V4_IMPORT = /@import\s*(?:'tailwindcss'|"tailwindcss")/
 const HAS_V4_THEME = /@theme\s*\{/
@@ -225,35 +225,35 @@ export async function loadDesignSystem(
   Object.assign(design, {
     dependencies: () => dependencies,
 
-    // TODOs:
-    //
-    // 1. Remove PostCSS parsing — its roughly 60% of the processing time
-    // ex: compiling 19k classes take 650ms and 400ms of that is PostCSS
-    //
-    // - Replace `candidatesToCss` with a `candidatesToAst` API
-    // First step would be to convert to a PostCSS AST by transforming the nodes directly
-    // Then it would be to drop the PostCSS AST representation entirely in all v4 code paths
-    compile(classes: string[]): postcss.Root[] {
+    compile(classes: string[]): AstNode[][] {
       // 1. Compile any uncached classes
-      let cache = design.storage[COMPILE_CACHE] as Record<string, postcss.Root>
+      let cache = design.storage[COMPILE_CACHE] as Record<string, AstNode[]>
       let uncached = classes.filter((name) => cache[name] === undefined)
 
-      let css = design.candidatesToCss(uncached)
+      let css = design.candidatesToAst
+        ? design.candidatesToAst(uncached)
+        : design.candidatesToCss(uncached)
+
       let errors: any[] = []
 
       for (let [idx, cls] of uncached.entries()) {
         let str = css[idx]
 
+        if (Array.isArray(str)) {
+          cache[cls] = str
+          continue
+        }
+
         if (str === null) {
-          cache[cls] = postcss.root()
+          cache[cls] = []
           continue
         }
 
         try {
-          cache[cls] = postcss.parse(str.trimEnd())
+          cache[cls] = parse(str.trimEnd())
         } catch (err) {
           errors.push(err)
-          cache[cls] = postcss.root()
+          cache[cls] = []
           continue
         }
       }
@@ -263,20 +263,14 @@ export async function loadDesignSystem(
       }
 
       // 2. Pull all the classes from the cache
-      let roots: postcss.Root[] = []
+      let roots: AstNode[][] = []
 
       for (let cls of classes) {
-        roots.push(cache[cls].clone())
+        roots.push(cache[cls].map(cloneAstNode))
       }
 
       return roots
     },
-
-    toCss(nodes: postcss.Root | postcss.Node[]): string {
-      return Array.isArray(nodes)
-        ? postcss.root({ nodes }).toString().trim()
-        : nodes.toString().trim()
-    },
   })
 
   return design

packages/tailwindcss-language-server/vitest.config.mts

@@ -14,9 +14,16 @@ export default defineConfig({
       name: 'force-inline-css',
       enforce: 'pre',
       resolveId(id) {
-        if (!id.includes('index.css')) return
         if (id.includes('?raw')) return
-        return this.resolve(`${id}?raw`)
+
+        if (
+          id.includes('index.css') ||
+          id.includes('theme.css') ||
+          id.includes('utilities.css') ||
+          id.includes('preflight.css')
+        ) {
+          return this.resolve(`${id}?raw`)
+        }
       },
     },
   ],

packages/tailwindcss-language-service/src/completionProvider.ts

@@ -47,6 +47,8 @@ import { resolveKnownThemeKeys, resolveKnownThemeNamespaces } from './util/v4/th
 import { SEARCH_RANGE } from './util/constants'
 import { getLanguageBoundaries } from './util/getLanguageBoundaries'
 import { isWithinRange } from './util/isWithinRange'
+import { walk, WalkAction } from './util/walk'
+import { Declaration, toPostCSSAst } from './css'
 
 let isUtil = (className) =>
   Array.isArray(className.__info)
@@ -2296,35 +2298,11 @@ export async function resolveCompletionItem(
     let base = state.designSystem.compile([className])[0]
     let root = state.designSystem.compile([[...variants, className].join(state.separator)])[0]
 
-    let rules = root.nodes.filter((node) => node.type === 'rule')
+    let rules = root.filter((node) => node.kind === 'rule')
     if (rules.length === 0) return item
 
     if (!item.detail) {
       if (rules.length === 1) {
-        let decls: postcss.Declaration[] = []
-
-        // Remove any `@property` rules
-        base = base.clone()
-        base.walkAtRules((rule) => {
-          // Ignore declarations inside `@property` rules
-          if (rule.name === 'property') {
-            rule.remove()
-          }
-
-          // Ignore declarations @supports (-moz-orient: inline)
-          // this is a hack used for `@property` fallbacks in Firefox
-          if (rule.name === 'supports' && rule.params === '(-moz-orient: inline)') {
-            rule.remove()
-          }
-
-          if (
-            rule.name === 'supports' &&
-            rule.params === '(background-image: linear-gradient(in lab, red, red))'
-          ) {
-            rule.remove()
-          }
-        })
-
         let ignoredValues = new Set([
           'var(--tw-border-style)',
           'var(--tw-outline-style)',
@@ -2334,26 +2312,51 @@ export async function resolveCompletionItem(
           'var(--tw-scale-x) var(--tw-scale-y) var(--tw-scale-z)',
         ])
 
-        base.walkDecls((node) => {
-          if (ignoredValues.has(node.value)) return
+        let decls: Declaration[] = []
+
+        walk(base, (node) => {
+          if (node.kind === 'at-rule') {
+            // Ignore declarations inside `@property` rules
+            if (node.name === '@property') {
+              return WalkAction.Skip
+            }
 
-          decls.push(node)
+            // Ignore declarations @supports (-moz-orient: inline)
+            // this is a hack used for `@property` fallbacks in Firefox
+            if (node.name === '@supports' && node.params === '(-moz-orient: inline)') {
+              return WalkAction.Skip
+            }
+
+            if (
+              node.name === '@supports' &&
+              node.params === '(background-image: linear-gradient(in lab, red, red))'
+            ) {
+              return WalkAction.Skip
+            }
+          }
+
+          if (node.kind === 'declaration') {
+            if (ignoredValues.has(node.value)) return WalkAction.Continue
+            decls.push(node)
+          }
+
+          return WalkAction.Continue
         })
 
         // TODO: Hardcoding this list is really unfortunate. We should be able
         // to handle this in Tailwind CSS itself.
-        function isOtherDecl(node: postcss.Declaration) {
-          if (node.prop === '--tw-leading') return false
-          if (node.prop === '--tw-duration') return false
-          if (node.prop === '--tw-ease') return false
-          if (node.prop === '--tw-font-weight') return false
-          if (node.prop === '--tw-gradient-via-stops') return false
-          if (node.prop === '--tw-gradient-stops') return false
-          if (node.prop === '--tw-tracking') return false
-          if (node.prop === '--tw-space-x-reverse' && node.value === '0') return false
-          if (node.prop === '--tw-space-y-reverse' && node.value === '0') return false
-          if (node.prop === '--tw-divide-x-reverse' && node.value === '0') return false
-          if (node.prop === '--tw-divide-y-reverse' && node.value === '0') return false
+        function isOtherDecl(node: Declaration) {
+          if (node.property === '--tw-leading') return false
+          if (node.property === '--tw-duration') return false
+          if (node.property === '--tw-ease') return false
+          if (node.property === '--tw-font-weight') return false
+          if (node.property === '--tw-gradient-via-stops') return false
+          if (node.property === '--tw-gradient-stops') return false
+          if (node.property === '--tw-tracking') return false
+          if (node.property === '--tw-space-x-reverse' && node.value === '0') return false
+          if (node.property === '--tw-space-y-reverse' && node.value === '0') return false
+          if (node.property === '--tw-divide-x-reverse' && node.value === '0') return false
+          if (node.property === '--tw-divide-y-reverse' && node.value === '0') return false
 
           return true
         }
@@ -2363,7 +2366,10 @@ export async function resolveCompletionItem(
           decls = decls.filter(isOtherDecl)
         }
 
-        item.detail = await jit.stringifyDecls(state, postcss.rule({ selectors: [], nodes: decls }))
+        let root = toPostCSSAst([{ kind: 'rule', selector: '', nodes: decls }])
+        let rule = root.nodes[0] as postcss.Rule
+
+        item.detail = await jit.stringifyDecls(state, rule)
       } else {
         item.detail = `${rules.length} rules`
       }
@@ -2373,8 +2379,9 @@ export async function resolveCompletionItem(
       item.documentation = {
         kind: 'markdown' as typeof MarkupKind.Markdown,
         value: [
+          //
           '```css',
-          await jit.stringifyRoot(state, postcss.root({ nodes: rules })),
+          await jit.stringifyRoot(state, toPostCSSAst(rules)),
           '```',
         ].join('\n'),
       }