Add matchUtilities and addUtilities APIs (#14114)

This PR introduces support for the v3-like `addUtilities` and
`matchUtilities` APIs in v4. We anticipate designing a new API that
feels more native to the way v4 works before shipping v4.0 stable, but
we're continuing to support these APIs for backwards compatibility.

We've tried to make the behavior as identical as possible, but because
of fundamental differences between the v3 and v4 engines there are a few
things that work differently:

## Only simple single-class selectors are supported

In v3 you could pass a complex CSS selector to `addUtilities` and we
would generate a utility for every class in the selector. In v4 we only
allow you to use a simple, single-class selector.

You should use nesting if you need a more complex selector, or need to
include at-rules like `@media` or `@supports`.

```js
// v3
function ({ addUtilities }) {
  addUtilities({
    '.scrollbar-none::-webkit-scrollbar': {
      display: 'none',
    },
  })
}

// v4
function ({ addUtilities }) {
  addUtilities({
    '.scrollbar-none': {
      '&::-webkit-scrollbar': {
        display: 'none',
      },
    },
  })
}
```

If you were adding custom utilities that included two classes and were
depending on both of those classes behaving like utilities (they could
each be used with variants), those custom utilities will need to be
rewritten as two separate utilities that each use nesting:

```js
// v3
function ({ addUtilities }) {
  addUtilities({
    '.section > .row': {
      color: 'red',
    },
  })
}

// v4
function ({ addUtilities }) {
  addUtilities({
    '.section': {
      '& > .row': {
        color: 'red',
      },
    },

    '.row': {
      'section > &': {
        color: 'red',
      },
    },
  })
}
```

We may introduce support for this in the future if this limitation turns
out to be a huge pain in the ass, but crossing our fingers that people
were mostly doing simple stuff here.

## Opacity modifiers support bare values

To be consistent with how built-in utilities work in v4, custom
utilities that specify `type: "color"` now get "bare value" support for
opacity modifiers. This means that a utility like `foo-black/33` will
work out of the box without having to either add `--opacity-33` to your
theme nor would you need to add it to the `modifiers` option.

## The `preferOnConflict` type option is gone

In v3 we introduced an internal API called `preferOnConflict` for types.
This was used as a way to disambiguate between two utilities with the
same "root" but which produced different properties which used the same
CSS data types. This was only applicable to arbitrary values and was
only used for disambiguating between `background-position` and
`background-size`.

In v4, both of these properties are handled by a single plugin meaning
this feature is no longer necessary. No one should've really been using
this option anyway as it was never documented so we're dropping the
feature.

## The options `respectPrefix` and `respectImportant` are not yet
supported

Neither the `prefix` nor `important` features exist in any form in v4 at
this time. Therefore, they are not currently supported by this PR. We
will look into supporting them if/when those features return.

## The `theme(…)` function is not currently supported

Custom utilities defined using `matchUtilities` often use the `theme(…)`
function to define their default values, but we haven't implemented
support for `theme(…)` yet in v4.

This means that as of this PR, default values for custom utilities must
be hardcoded:

```js
function ({ matchUtilities }) {
  matchUtilities({
    'tab': (value) => {
      return {
        'tab-size': value,
      }
    },
  }, {
    values: {
      2: '2',
      4: '4',
      8: '8',
    },
  })
}
```

Getting `theme(…)` working is a big project so we're going to tackle it
in a separate PR.

---------

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

Author: 3 people

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add `inert` variant ([#14129](https://github.com/tailwindlabs/tailwindcss/pull/14129))
 - Add support for explicitly registering content paths using new `@source` at-rule ([#14078](https://github.com/tailwindlabs/tailwindcss/pull/14078))
 - Add support for scanning `<style>` tags in Vue files to the Vite plugin ([#14158](https://github.com/tailwindlabs/tailwindcss/pull/14158))
+- Add support for basic `addUtilities` and `matchUtilities` plugins using the `@plugin` directive ([#14114](https://github.com/tailwindlabs/tailwindcss/pull/14114))
 
 ### Fixed
 

packages/tailwindcss/src/apply.ts

@@ -0,0 +1,70 @@
+import { walk, type AstNode } from './ast'
+import { compileCandidates } from './compile'
+import type { DesignSystem } from './design-system'
+import { escape } from './utils/escape'
+
+export function substituteAtApply(ast: AstNode[], designSystem: DesignSystem) {
+  walk(ast, (node, { replaceWith }) => {
+    if (node.kind !== 'rule') return
+    if (!(node.selector[0] === '@' && node.selector.startsWith('@apply '))) return
+
+    let candidates = node.selector
+      .slice(7 /* Ignore `@apply ` when parsing the selector */)
+      .trim()
+      .split(/\s+/g)
+
+    // Replace the `@apply` rule with the actual utility classes
+    {
+      // Parse the candidates to an AST that we can replace the `@apply` rule
+      // with.
+      let candidateAst = compileCandidates(candidates, designSystem, {
+        onInvalidCandidate: (candidate) => {
+          throw new Error(`Cannot apply unknown utility class: ${candidate}`)
+        },
+      }).astNodes
+
+      // Collect the nodes to insert in place of the `@apply` rule. When a rule
+      // was used, we want to insert its children instead of the rule because we
+      // don't want the wrapping selector.
+      let newNodes: AstNode[] = []
+      for (let candidateNode of candidateAst) {
+        if (candidateNode.kind === 'rule' && candidateNode.selector[0] !== '@') {
+          for (let child of candidateNode.nodes) {
+            newNodes.push(child)
+          }
+        } else {
+          newNodes.push(candidateNode)
+        }
+      }
+
+      // Verify that we don't have any circular dependencies by verifying that
+      // the current node does not appear in the new nodes.
+      walk(newNodes, (child) => {
+        if (child !== node) return
+
+        // At this point we already know that we have a circular dependency.
+        //
+        // Figure out which candidate caused the circular dependency. This will
+        // help to create a useful error message for the end user.
+        for (let candidate of candidates) {
+          let selector = `.${escape(candidate)}`
+
+          for (let rule of candidateAst) {
+            if (rule.kind !== 'rule') continue
+            if (rule.selector !== selector) continue
+
+            walk(rule.nodes, (child) => {
+              if (child !== node) return
+
+              throw new Error(
+                `You cannot \`@apply\` the \`${candidate}\` utility here because it creates a circular dependency.`,
+              )
+            })
+          }
+        }
+      })
+
+      replaceWith(newNodes)
+    }
+  })
+}

packages/tailwindcss/src/ast.ts

@@ -52,6 +52,10 @@ export function objectToAst(obj: CssInJs): AstNode[] {
       if (!name.startsWith('--') && value === '@slot') {
         ast.push(rule(name, [rule('@slot', [])]))
       } else {
+        // Convert camelCase to kebab-case:
+        // https://github.com/postcss/postcss-js/blob/b3db658b932b42f6ac14ca0b1d50f50c4569805b/parser.js#L30-L35
+        name = name.replace(/([A-Z])/g, '-$1').toLowerCase()
+
         ast.push(decl(name, value))
       }
     } else {

packages/tailwindcss/src/compile.ts

@@ -1,7 +1,8 @@
-import { WalkAction, rule, walk, type AstNode, type Rule } from './ast'
+import { WalkAction, decl, rule, walk, type AstNode, type Rule } from './ast'
 import { type Candidate, type Variant } from './candidate'
 import { type DesignSystem } from './design-system'
 import GLOBAL_PROPERTY_ORDER from './property-order'
+import { asColor } from './utilities'
 import { compare } from './utils/compare'
 import { escape } from './utils/escape'
 import type { Variants } from './variants'
@@ -102,39 +103,9 @@ export function compileAstNodes(rawCandidate: string, designSystem: DesignSystem
   let candidate = designSystem.parseCandidate(rawCandidate)
   if (candidate === null) return null
 
-  let nodes: AstNode[] = []
+  let nodes = compileBaseUtility(candidate, designSystem)
 
-  // Handle arbitrary properties
-  if (candidate.kind === 'arbitrary') {
-    let compileFn = designSystem.utilities.getArbitrary()
-
-    // Build the node
-    let compiledNodes = compileFn(candidate)
-    if (compiledNodes === undefined) return null
-
-    nodes = compiledNodes
-  }
-
-  // Handle named utilities
-  else if (candidate.kind === 'static' || candidate.kind === 'functional') {
-    let fns = designSystem.utilities.get(candidate.root)
-
-    // Build the node
-    let compiledNodes: AstNode[] | undefined
-
-    for (let i = fns.length - 1; i >= 0; i--) {
-      let fn = fns[i]
-
-      if (candidate.kind !== fn.kind) continue
-
-      compiledNodes = fn.compileFn(candidate)
-      if (compiledNodes) break
-    }
-
-    if (compiledNodes === undefined) return null
-
-    nodes = compiledNodes
-  }
+  if (!nodes) return null
 
   let propertySort = getPropertySort(nodes)
 
@@ -226,6 +197,36 @@ export function applyVariant(node: Rule, variant: Variant, variants: Variants):
   if (result === null) return null
 }
 
+function compileBaseUtility(candidate: Candidate, designSystem: DesignSystem) {
+  if (candidate.kind === 'arbitrary') {
+    let value: string | null = candidate.value
+
+    // Assumption: If an arbitrary property has a modifier, then we assume it
+    // is an opacity modifier.
+    if (candidate.modifier) {
+      value = asColor(value, candidate.modifier, designSystem.theme)
+    }
+
+    if (value === null) return
+
+    return [decl(candidate.property, value)]
+  }
+
+  let utilities = designSystem.utilities.get(candidate.root) ?? []
+
+  for (let i = utilities.length - 1; i >= 0; i--) {
+    let utility = utilities[i]
+
+    if (candidate.kind !== utility.kind) continue
+
+    let compiledNodes = utility.compileFn(candidate)
+    if (compiledNodes === null) return null
+    if (compiledNodes) return compiledNodes
+  }
+
+  return null
+}
+
 function applyImportant(ast: AstNode[]): void {
   for (let node of ast) {
     // Skip any `@at-root` rules — we don't want to make the contents of things

packages/tailwindcss/src/index.ts

@@ -1,29 +1,15 @@
 import { version } from '../package.json'
-import {
-  WalkAction,
-  comment,
-  decl,
-  objectToAst,
-  rule,
-  toCss,
-  walk,
-  type AstNode,
-  type CssInJs,
-  type Rule,
-} from './ast'
+import { substituteAtApply } from './apply'
+import { WalkAction, comment, decl, rule, toCss, walk, type Rule } from './ast'
 import { compileCandidates } from './compile'
 import * as CSS from './css-parser'
 import { buildDesignSystem, type DesignSystem } from './design-system'
+import { buildPluginApi, type PluginAPI } from './plugin-api'
 import { Theme } from './theme'
-import { escape } from './utils/escape'
 import { segment } from './utils/segment'
 
 const IS_VALID_UTILITY_NAME = /^[a-z][a-zA-Z0-9/%._-]*$/
 
-type PluginAPI = {
-  addVariant(name: string, variant: string | string[] | CssInJs): void
-}
-
 type Plugin = (api: PluginAPI) => void
 
 type CompileOptions = {
@@ -311,30 +297,9 @@ export async function compile(
     customUtility(designSystem)
   }
 
-  let api: PluginAPI = {
-    addVariant(name, variant) {
-      // Single selector
-      if (typeof variant === 'string') {
-        designSystem.variants.static(name, (r) => {
-          r.nodes = [rule(variant, r.nodes)]
-        })
-      }
-
-      // Multiple parallel selectors
-      else if (Array.isArray(variant)) {
-        designSystem.variants.static(name, (r) => {
-          r.nodes = variant.map((selector) => rule(selector, r.nodes))
-        })
-      }
-
-      // CSS-in-JS object
-      else if (typeof variant === 'object') {
-        designSystem.variants.fromAst(name, objectToAst(variant))
-      }
-    },
-  }
+  let pluginApi = buildPluginApi(designSystem)
 
-  await Promise.all(pluginLoaders.map((loader) => loader.then((plugin) => plugin(api))))
+  await Promise.all(pluginLoaders.map((loader) => loader.then((plugin) => plugin(pluginApi))))
 
   let tailwindUtilitiesNode: Rule | null = null
 
@@ -420,72 +385,6 @@ export async function compile(
   }
 }
 
-function substituteAtApply(ast: AstNode[], designSystem: DesignSystem) {
-  walk(ast, (node, { replaceWith }) => {
-    if (node.kind !== 'rule') return
-    if (!(node.selector[0] === '@' && node.selector.startsWith('@apply '))) return
-
-    let candidates = node.selector
-      .slice(7 /* Ignore `@apply ` when parsing the selector */)
-      .trim()
-      .split(/\s+/g)
-
-    // Replace the `@apply` rule with the actual utility classes
-    {
-      // Parse the candidates to an AST that we can replace the `@apply` rule
-      // with.
-      let candidateAst = compileCandidates(candidates, designSystem, {
-        onInvalidCandidate: (candidate) => {
-          throw new Error(`Cannot apply unknown utility class: ${candidate}`)
-        },
-      }).astNodes
-
-      // Collect the nodes to insert in place of the `@apply` rule. When a rule
-      // was used, we want to insert its children instead of the rule because we
-      // don't want the wrapping selector.
-      let newNodes: AstNode[] = []
-      for (let candidateNode of candidateAst) {
-        if (candidateNode.kind === 'rule' && candidateNode.selector[0] !== '@') {
-          for (let child of candidateNode.nodes) {
-            newNodes.push(child)
-          }
-        } else {
-          newNodes.push(candidateNode)
-        }
-      }
-
-      // Verify that we don't have any circular dependencies by verifying that
-      // the current node does not appear in the new nodes.
-      walk(newNodes, (child) => {
-        if (child !== node) return
-
-        // At this point we already know that we have a circular dependency.
-        //
-        // Figure out which candidate caused the circular dependency. This will
-        // help to create a useful error message for the end user.
-        for (let candidate of candidates) {
-          let selector = `.${escape(candidate)}`
-
-          for (let rule of candidateAst) {
-            if (rule.kind !== 'rule') continue
-            if (rule.selector !== selector) continue
-
-            walk(rule.nodes, (child) => {
-              if (child !== node) return
-
-              throw new Error(
-                `You cannot \`@apply\` the \`${candidate}\` utility here because it creates a circular dependency.`,
-              )
-            })
-          }
-        }
-      })
-
-      replaceWith(newNodes)
-    }
-  })
-}
-
 export function __unstable__loadDesignSystem(css: string) {
   // Find all `@theme` declarations
   let theme = new Theme()