Fix theme() in JS plugins returning unresolved object instead of DEFAULT value

[koreahghg]

Summary

When a CSS theme key defined via @theme (or a JS config's theme object) shares a dash-separated prefix with a sibling key — e.g. --color-foo and --color-foo-bar — calling theme('colors.foo') from inside a JS plugin (addUtilities, addComponents, etc.) does not resolve to the foo value. Instead it returns an internal disambiguation object shaped like { DEFAULT: 'red', bar: 'blue', __CSS_VALUES__: {...} }, because there's no way to tell from CSS custom property names alone whether foo-bar is a sibling key or a nested sub-key of foo.

This same ambiguity was already fixed for the CSS-embedded theme() function in #19097 (which unwraps to the DEFAULT key when present), and the changelog entry for that PR states it fixes this "in JS configs and plugins" — but the fix only touched apply-compat-hooks.ts's resolveThemeValue, not createThemeFn's theme function that's exposed directly to plugins in plugin-functions.ts. This PR closes that gap by applying the same DEFAULT-unwrapping there.

Without this fix, passing the raw object into addUtilities (a very natural thing to do, since a plugin author expects a string) produces broken CSS — the reserved DEFAULT key gets mangled into a garbage property name (-d-e-f-a-u-l-t) by the kebab-case conversion, and the internal __CSS_VALUES__ bookkeeping leaks into the generated stylesheet.

Minimal reproduction

// tailwind.config.js (registered via @config, or any @plugin-registered plugin)
const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function ({ addUtilities, theme }) {
      addUtilities({
        '.example-foo': { color: theme('colors.foo') },
      })
    }),
  ],
}

@import "tailwindcss";
@config "./tailwind.config.js";
@theme {
  --color-foo: red;
  --color-foo-bar: blue;
}

Before:

.example-foo color {
  -d-e-f-a-u-l-t: red;
  bar: blue;
}
.example-foo color __CSS_VALUES__ {
  -d-e-f-a-u-l-t: 0;
  bar: 0;
}

After:

.example-foo {
  color: red;
}

Test plan

• Added a regression test in packages/tailwindcss/src/compat/plugin-api.test.ts ("theme() resolves the DEFAULT value when a bare CSS theme key shares a prefix with a sibling key")
• Verified via pnpm --filter tailwindcss exec vitest run that this test fails with the exact broken output shown above when the fix is reverted, and passes once it's applied
• Ran the full tailwindcss package test suite (pnpm --filter tailwindcss exec vitest run) — 4684 tests passing, no regressions
• Verified formatting on the changed files with npx prettier --check

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: b77acfa8-6652-4b62-ad08-72973ca3ba04

📥 Commits

Reviewing files that changed from the base of the PR and between 0d62152 and 2a38bd7.

📒 Files selected for processing (3)

• CHANGELOG.md
• packages/tailwindcss/src/compat/plugin-api.test.ts
• packages/tailwindcss/src/compat/plugin-functions.ts

✅ Files skipped from review due to trivial changes (1)

• CHANGELOG.md

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/tailwindcss/src/compat/plugin-functions.ts
• packages/tailwindcss/src/compat/plugin-api.test.ts

---

Walkthrough

This change updates theme() in JS plugins to return cssValue.DEFAULT when a synthetic CSS object with a DEFAULT key is encountered. It adds a test covering theme('colors.foo') and theme('colors.foo-bar') for prefix-sharing keys, and adds a changelog entry describing the fix.

Changes

• packages/tailwindcss/src/compat/plugin-functions.ts: added DEFAULT object handling in theme().
• packages/tailwindcss/src/compat/plugin-api.test.ts: added coverage for shared-prefix theme key resolution.
• CHANGELOG.md: added a fixed-entry note for the behavior change.

Sequence Diagram(s)

sequenceDiagram
  participant Plugin
  participant ThemeFn
  participant CssResolver

  Plugin->>ThemeFn: theme('colors.foo')
  ThemeFn->>CssResolver: resolve cssValue
  CssResolver-->>ThemeFn: synthetic object with DEFAULT
  ThemeFn->>ThemeFn: return cssValue.DEFAULT
  ThemeFn-->>Plugin: resolved color value

Loading

Related PRs: None specified.

Suggested labels: bug, compat

Suggested reviewers: None specified.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main fix: JS plugin theme() now unwraps DEFAULT instead of returning an unresolved object.
Description check	✅ Passed	The description is detailed and directly matches the change, including the bug, fix, and regression test.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

CHANGELOG.md (1)

14-14: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Missing PR reference link.

Sibling entries (lines 12-13) include a ([#XXXXX](...)) PR link; this new entry doesn't. Worth adding for consistency once the PR number is known.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 8e43882d-33df-4c07-9ea5-dba59ca9c2e7

📥 Commits

Reviewing files that changed from the base of the PR and between e46b3d7 and b870cdd.

📒 Files selected for processing (3)

• CHANGELOG.md
• packages/tailwindcss/src/compat/plugin-api.test.ts
• packages/tailwindcss/src/compat/plugin-functions.ts

[greptile-apps]

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

_{Reviews (3): Last reviewed commit: "update CHANGELOG" | Re-trigger Greptile}

[RobinMalfait]

Thanks! Made a few small changes to the comment / changelog entry.