Make config resolution lazy (#14362)

The internal `registerPlugins()` API is used to enable backwards
compatibility with v3 plugins and configs and it is called on every
build even when no v3 plugins or configs are used. This function has a
non-trivial cost in that case — around 5ms.

So this PR does a few things:

## Implements a simpler, faster `theme(…)` function

We now have a much simpler `theme(…)` function that can be used when
backwards compatibility is not necessary. It still supports many of the
same features:
- The modern, v4 style CSS variable syntax `theme(--color-red-500)`
- The legacy, v3 path style `theme(colors.red.500)`
- And the v3-style alpha modifier `theme(colors.red.500 / 50%)`
- Path upgrades so things like `theme(accentColor.red.500)` pulls from
`--color-red-500` when no `--accent-color-red-500` theme key exists

When you do have plugins or configs the more advanced `theme(…)`
function is swapped in for more complete backwards compatibility.

## `registerPlugins` registers globs

Before `registerPlugins` passed the `ResolvedConfig` out so we could
register globs in `compile()`. Since that one function is really the
main driver for backwards compat we decided to move the content path
registration into `registerPlugins` itself when it comes to paths
provided by plugins and configs.

This is an internal implementation detail (well this entire PR is) but
it's worth mentioning. This method is used to resolve a theme value from
a theme key.

## `registerPlugins` is now only called when necessary

All of the above work made it so that `registerPlugins` can be called
only as needed. This means that when no v3 plugins or configs are used,
`registerPlugins` is never called thus elminating the performance impact
of config resolution.

---------

Co-authored-by: Adam Wathan <[email protected]>

Author: thecrypticace

packages/tailwindcss/src/compat/plugin-functions.ts

@@ -11,7 +11,7 @@ export function createThemeFn(
   configTheme: () => UserConfig['theme'],
   resolveValue: (value: any) => any,
 ) {
-  return function theme(path: string, defaultValue?: any) {
+  return function theme(path: string, defaultValue?: unknown) {
     // Extract an eventual modifier from the path. e.g.:
     // - "colors.red.500 / 50%" -> "50%"
     // - "foo/bar/baz/50%"      -> "50%"
@@ -148,7 +148,7 @@ function readFromCss(
     () => new Map(),
   )
 
-  let ns = theme.namespace(`--${themeKey}` as any)
+  let ns = theme.namespace(`--${themeKey}`)
   if (ns.size === 0) {
     return [null, ThemeOptions.NONE]
   }

packages/tailwindcss/src/css-functions.test.ts

@@ -288,9 +288,13 @@ describe('theme function', () => {
           `)
         })
 
-        test('theme(fontFamily.sans)', async () => {
+        test('theme(fontFamily.sans) (css)', async () => {
           expect(
             await compileCss(css`
+              @theme default reference {
+                --font-family-sans: ui-sans-serif, system-ui, sans-serif, Apple Color Emoji,
+                  Segoe UI Emoji, Segoe UI Symbol, Noto Color Emoji;
+              }
               .fam {
                 font-family: theme(fontFamily.sans);
               }
@@ -301,6 +305,26 @@ describe('theme function', () => {
           }"
         `)
         })
+
+        test('theme(fontFamily.sans) (config)', async () => {
+          let compiled = await compile(
+            css`
+              @config "./my-config.js";
+              .fam {
+                font-family: theme(fontFamily.sans);
+              }
+            `,
+            {
+              loadConfig: async () => ({}),
+            },
+          )
+
+          expect(optimizeCss(compiled.build([])).trim()).toMatchInlineSnapshot(`
+          ".fam {
+            font-family: ui-sans-serif, system-ui, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol, Noto Color Emoji;
+          }"
+        `)
+        })
       })
 
       test('theme(colors.unknown.500)', async () =>

packages/tailwindcss/src/css-functions.ts

@@ -1,15 +1,16 @@
 import { walk, type AstNode } from './ast'
-import type { PluginAPI } from './plugin-api'
 import * as ValueParser from './value-parser'
 import { type ValueAstNode } from './value-parser'
 
 export const THEME_FUNCTION_INVOCATION = 'theme('
 
-export function substituteFunctions(ast: AstNode[], pluginApi: PluginAPI) {
+type ResolveThemeValue = (path: string) => unknown
+
+export function substituteFunctions(ast: AstNode[], resolveThemeValue: ResolveThemeValue) {
   walk(ast, (node) => {
     // Find all declaration values
     if (node.kind === 'declaration' && node.value?.includes(THEME_FUNCTION_INVOCATION)) {
-      node.value = substituteFunctionsInValue(node.value, pluginApi)
+      node.value = substituteFunctionsInValue(node.value, resolveThemeValue)
       return
     }
 
@@ -23,13 +24,16 @@ export function substituteFunctions(ast: AstNode[], pluginApi: PluginAPI) {
           node.selector.startsWith('@supports ')) &&
         node.selector.includes(THEME_FUNCTION_INVOCATION)
       ) {
-        node.selector = substituteFunctionsInValue(node.selector, pluginApi)
+        node.selector = substituteFunctionsInValue(node.selector, resolveThemeValue)
       }
     }
   })
 }
 
-export function substituteFunctionsInValue(value: string, pluginApi: PluginAPI): string {
+export function substituteFunctionsInValue(
+  value: string,
+  resolveThemeValue: ResolveThemeValue,
+): string {
   let ast = ValueParser.parse(value)
   ValueParser.walk(ast, (node, { replaceWith }) => {
     if (node.kind === 'function' && node.value === 'theme') {
@@ -67,26 +71,25 @@ export function substituteFunctionsInValue(value: string, pluginApi: PluginAPI):
       path = eventuallyUnquote(path)
       let fallbackValues = node.nodes.slice(skipUntilIndex + 1)
 
-      replaceWith(cssThemeFn(pluginApi, path, fallbackValues))
+      replaceWith(cssThemeFn(resolveThemeValue, path, fallbackValues))
     }
   })
 
   return ValueParser.toCss(ast)
 }
 
 function cssThemeFn(
-  pluginApi: PluginAPI,
+  resolveThemeValue: ResolveThemeValue,
   path: string,
   fallbackValues: ValueAstNode[],
 ): ValueAstNode[] {
   let resolvedValue: string | null = null
-  let themeValue = pluginApi.theme(path)
+  let themeValue = resolveThemeValue(path)
 
-  let isArray = Array.isArray(themeValue)
-  if (isArray && themeValue.length === 2) {
+  if (Array.isArray(themeValue) && themeValue.length === 2) {
     // When a tuple is returned, return the first element
     resolvedValue = themeValue[0]
-  } else if (isArray) {
+  } else if (Array.isArray(themeValue)) {
     // Arrays get serialized into a comma-separated lists
     resolvedValue = themeValue.join(', ')
   } else if (typeof themeValue === 'string') {

packages/tailwindcss/src/design-system.ts

@@ -4,6 +4,7 @@ import { compileAstNodes, compileCandidates } from './compile'
 import { getClassList, getVariants, type ClassEntry, type VariantEntry } from './intellisense'
 import { getClassOrder } from './sort'
 import type { Theme } from './theme'
+import { resolveThemeValue } from './theme-fn'
 import { Utilities, createUtilities } from './utilities'
 import { DefaultMap } from './utils/default-map'
 import { Variants, createVariants } from './variants'
@@ -23,6 +24,7 @@ export type DesignSystem = {
   compileAstNodes(candidate: Candidate): ReturnType<typeof compileAstNodes>
 
   getUsedVariants(): ReturnType<typeof parseVariant>[]
+  resolveThemeValue(path: string, defaultValue?: string): string | undefined
 }
 
 export function buildDesignSystem(theme: Theme): DesignSystem {
@@ -79,6 +81,10 @@ export function buildDesignSystem(theme: Theme): DesignSystem {
     getUsedVariants() {
       return Array.from(parsedVariants.values())
     },
+
+    resolveThemeValue(path: string, defaultValue?: string) {
+      return resolveThemeValue(theme, path, defaultValue)
+    },
   }
 
   return designSystem

packages/tailwindcss/src/index.ts

@@ -321,7 +321,9 @@ async function parseCss(
     })),
   )
 
-  let { pluginApi, resolvedConfig } = registerPlugins(plugins, designSystem, ast, configs)
+  if (plugins.length || configs.length) {
+    registerPlugins(plugins, designSystem, ast, configs, globs)
+  }
 
   for (let customVariant of customVariants) {
     customVariant(designSystem)
@@ -379,7 +381,7 @@ async function parseCss(
   // also contain functions or plugins that use functions so we need to evaluate
   // functions if either of those are present.
   if (plugins.length > 0 || configs.length > 0 || css.includes(THEME_FUNCTION_INVOCATION)) {
-    substituteFunctions(ast, pluginApi)
+    substituteFunctions(ast, designSystem.resolveThemeValue)
   }
 
   // Remove `@utility`, we couldn't replace it before yet because we had to
@@ -396,19 +398,8 @@ async function parseCss(
     return WalkAction.Skip
   })
 
-  for (let file of resolvedConfig.content.files) {
-    if ('raw' in file) {
-      throw new Error(
-        `Error in the config file/plugin/preset. The \`content\` key contains a \`raw\` entry:\n\n${JSON.stringify(file, null, 2)}\n\nThis feature is not currently supported.`,
-      )
-    }
-
-    globs.push({ origin: file.base, pattern: file.pattern })
-  }
-
   return {
     designSystem,
-    pluginApi,
     ast,
     globs,
   }
@@ -421,7 +412,7 @@ export async function compile(
   globs: { origin?: string; pattern: string }[]
   build(candidates: string[]): string
 }> {
-  let { designSystem, ast, globs, pluginApi } = await parseCss(css, opts)
+  let { designSystem, ast, globs } = await parseCss(css, opts)
 
   let tailwindUtilitiesNode: Rule | null = null
 
@@ -491,7 +482,7 @@ export async function compile(
         // properties (`[--my-var:theme(--color-red-500)]`) can contain function
         // calls so we need evaluate any functions we find there that weren't in
         // the source CSS.
-        substituteFunctions(newNodes, pluginApi)
+        substituteFunctions(newNodes, designSystem.resolveThemeValue)
 
         previousAstNodeCount = newNodes.length
 

packages/tailwindcss/src/plugin-api.ts

@@ -360,6 +360,7 @@ export function registerPlugins(
   designSystem: DesignSystem,
   ast: AstNode[],
   configs: ConfigFile[],
+  globs: { origin?: string; pattern: string }[],
 ) {
   let plugins = pluginDetails.map((detail) => {
     if (!detail.options) {
@@ -392,8 +393,17 @@ export function registerPlugins(
   // core utilities already read from.
   applyConfigToTheme(designSystem, userConfig)
 
-  return {
-    pluginApi,
-    resolvedConfig,
+  designSystem.resolveThemeValue = function resolveThemeValue(path: string, defaultValue?: string) {
+    return pluginApi.theme(path, defaultValue)
+  }
+
+  for (let file of resolvedConfig.content.files) {
+    if ('raw' in file) {
+      throw new Error(
+        `Error in the config file/plugin/preset. The \`content\` key contains a \`raw\` entry:\n\n${JSON.stringify(file, null, 2)}\n\nThis feature is not currently supported.`,
+      )
+    }
+
+    globs.push({ origin: file.base, pattern: file.pattern })
   }
 }

packages/tailwindcss/src/theme-fn.ts

@@ -0,0 +1,129 @@
+import type { Theme, ThemeKey } from './theme'
+import { withAlpha } from './utilities'
+import { toKeyPath } from './utils/to-key-path'
+
+/**
+ * Looks up a value in the CSS theme
+ */
+export function resolveThemeValue(theme: Theme, path: string, defaultValue?: string) {
+  // Extract an eventual modifier from the path. e.g.:
+  // - "colors.red.500 / 50%" -> "50%"
+  // - "foo/bar/baz/50%"      -> "50%"
+  let lastSlash = path.lastIndexOf('/')
+  let modifier: string | null = null
+  if (lastSlash !== -1) {
+    modifier = path.slice(lastSlash + 1).trim()
+    path = path.slice(0, lastSlash).trim()
+  }
+
+  let themeValue = lookupThemeValue(theme, path, defaultValue)
+
+  // Apply the opacity modifier if present
+  if (modifier && typeof themeValue === 'string') {
+    return withAlpha(themeValue, modifier)
+  }
+
+  return themeValue
+}
+
+function toThemeKey(keypath: string[]) {
+  return (
+    keypath
+      // [1] should move into the nested object tuple. To create the CSS variable
+      // name for this, we replace it with an empty string that will result in two
+      // subsequent dashes when joined.
+      .map((path) => (path === '1' ? '' : path))
+
+      // Resolve the key path to a CSS variable segment
+      .map((part) =>
+        part
+          .replaceAll('.', '_')
+          .replace(/([a-z])([A-Z])/g, (_, a, b) => `${a}-${b.toLowerCase()}`),
+      )
+
+      // Remove the `DEFAULT` key at the end of a path
+      // We're reading from CSS anyway so it'll be a string
+      .filter((part, index) => part !== 'DEFAULT' || index !== keypath.length - 1)
+      .join('-')
+  )
+}
+
+function lookupThemeValue(theme: Theme, path: string, defaultValue?: string) {
+  if (path.startsWith('--')) {
+    return theme.get([path as any]) ?? defaultValue
+  }
+
+  let baseThemeKey = '--' + toThemeKey(toKeyPath(path))
+
+  let resolvedValue = theme.get([baseThemeKey as ThemeKey])
+
+  if (resolvedValue !== null) {
+    return resolvedValue
+  }
+
+  for (let [givenKey, upgradeKey] of Object.entries(themeUpgradeKeys)) {
+    if (!baseThemeKey.startsWith(givenKey)) continue
+
+    let upgradedKey = upgradeKey + baseThemeKey.slice(givenKey.length)
+    let resolvedValue = theme.get([upgradedKey as ThemeKey])
+
+    if (resolvedValue !== null) {
+      return resolvedValue
+    }
+  }
+
+  return defaultValue
+}
+
+let themeUpgradeKeys = {
+  '--colors': '--color',
+  '--accent-color': '--color',
+  '--backdrop-blur': '--blur',
+  '--backdrop-brightness': '--brightness',
+  '--backdrop-contrast': '--contrast',
+  '--backdrop-grayscale': '--grayscale',
+  '--backdrop-hue-rotate': '--hueRotate',
+  '--backdrop-invert': '--invert',
+  '--backdrop-opacity': '--opacity',
+  '--backdrop-saturate': '--saturate',
+  '--backdrop-sepia': '--sepia',
+  '--background-color': '--color',
+  '--background-opacity': '--opacity',
+  '--border-color': '--color',
+  '--border-opacity': '--opacity',
+  '--border-spacing': '--spacing',
+  '--box-shadow-color': '--color',
+  '--caret-color': '--color',
+  '--divide-color': '--borderColor',
+  '--divide-opacity': '--borderOpacity',
+  '--divide-width': '--borderWidth',
+  '--fill': '--color',
+  '--flex-basis': '--spacing',
+  '--gap': '--spacing',
+  '--gradient-color-stops': '--color',
+  '--height': '--spacing',
+  '--inset': '--spacing',
+  '--margin': '--spacing',
+  '--max-height': '--spacing',
+  '--max-width': '--spacing',
+  '--min-height': '--spacing',
+  '--min-width': '--spacing',
+  '--outline-color': '--color',
+  '--padding': '--spacing',
+  '--placeholder-color': '--color',
+  '--placeholder-opacity': '--opacity',
+  '--ring-color': '--color',
+  '--ring-offset-color': '--color',
+  '--ring-opacity': '--opacity',
+  '--scroll-margin': '--spacing',
+  '--scroll-padding': '--spacing',
+  '--space': '--spacing',
+  '--stroke': '--color',
+  '--text-color': '--color',
+  '--text-decoration-color': '--color',
+  '--text-indent': '--spacing',
+  '--text-opacity': '--opacity',
+  '--translate': '--spacing',
+  '--size': '--spacing',
+  '--width': '--spacing',
+}