Skip to content

feat: add cssPropertyRename option to prevent CSS @property conflicts#2005

Open
taiiiyang wants to merge 2 commits intowxt-dev:mainfrom
taiiiyang:implement-custom-css-property-prefix
Open

feat: add cssPropertyRename option to prevent CSS @property conflicts#2005
taiiiyang wants to merge 2 commits intowxt-dev:mainfrom
taiiiyang:implement-custom-css-property-prefix

Conversation

@taiiiyang
Copy link

@taiiiyang taiiiyang commented Dec 17, 2025

Overview

Add cssPropertyRename option to createShadowRootUi that allows renaming CSS custom property prefixes to prevent
conflicts with host page styles.

Problem:
When extensions use Tailwind CSS v4 with Shadow Root UI, the @property rules (e.g., @property --tw-gradient-from { syntax: "<color>"; }) are extracted and injected into the host page's <head>. This causes conflicts with host pages
using Tailwind CSS v3, which use composite CSS variable values that don't match the typed syntax constraint.

Solution:

  • Added renameCssCustomProperties() utility function that renames:
    • @property rules: @property --tw-xxx → @property --wxt-tw-xxx
    • Property declarations: --tw-xxx: value → --wxt-tw-xxx: value
    • var() references: var(--tw-xxx) → var(--wxt-tw-xxx)
  • Added cssPropertyRename option to ShadowRootContentScriptUiOptions
  • Both fromPrefix and toPrefix are optional:
    • If only toPrefix is provided: prepends prefix to all custom properties
    • If only fromPrefix is provided: removes the matching prefix
    • If both are provided: replaces fromPrefix with toPrefix

Manual Testing

  1. Create a WXT extension with Shadow Root UI using Tailwind CSS v4:
createShadowRootUi(ctx, {
  name: 'my-ui',
  cssPropertyRename: {
    fromPrefix: '--tw-',
    toPrefix: '--my-ext-tw-',
  },
  onMount(container) {
    // ...
  },
});
  1. Build the extension and load it in the browser
  2. Visit a website using Tailwind CSS v3 with gradients (e.g., https://yesicon.app/ph)
  3. Verify that the host page's gradient styles are NOT broken
  4. Verify that the extension's styles work correctly

Related Issue

This PR closes #1955

@netlify
Copy link

netlify bot commented Dec 17, 2025 •
edited
Loading

❌ Deploy Preview for creative-fairy-df92c4 failed.

Name Link
🔨 Latest commit 49ed882
🔍 Latest deploy log https://app.netlify.com/projects/creative-fairy-df92c4/deploys/6948fcca1037da0008379d45

aklinker1
aklinker1 requested changes Dec 18, 2025
View reviewed changes
Copy link
Member

@aklinker1 aklinker1 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code looks good, thanks for writing tests.

We had really bad performance with the splitShadowRootCss function that some else found and improved. Since that function and this new one both are apart of the same function, createShadowRootUi, and slow performance here is known to cause a bad UX, can you benchmark the createShadowRootUi function using real CSS from tailwind?

Compare how many times per second createShadowRootUi can run with or without cssPropertyRename. If it's slow, try and optimize it. If it's fast and the hit is negligable, no need to make any improvements.

You can use Vitest's bench utils to write the benchmark, please include it in the PR, don't just delete it after writing it.

@taiiiyang taiiiyang requested a review from aklinker1 December 22, 2025 08:11
@taiiiyang
Copy link
Author

taiiiyang commented Dec 22, 2025

Code looks good, thanks for writing tests.

We had really bad performance with the splitShadowRootCss function that some else found and improved. Since that function and this new one both are apart of the same function, createShadowRootUi, and slow performance here is known to cause a bad UX, can you benchmark the createShadowRootUi function using real CSS from tailwind?

Compare how many times per second createShadowRootUi can run with or without cssPropertyRename. If it's slow, try and optimize it. If it's fast and the hit is negligable, no need to make any improvements.

You can use Vitest's bench utils to write the benchmark, please include it in the PR, don't just delete it after writing it.

I have made adjustments to the current renameCssCustomProperties method, and now there are no performance issues. Here are the test results obtained using vitest bench.

1766391294599

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Timeraa Timeraa Awaiting requested review from Timeraa Timeraa is a code owner

@aklinker1 aklinker1 Awaiting requested review from aklinker1 aklinker1 is a code owner

Requested changes must be addressed to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

CSS @property conflicts when extension uses Tailwind v4 and host page uses Tailwind v3

2 participants

@taiiiyang @aklinker1