feat(vite-plugin): Shadow DOM isolation for content scripts

[Toumash]

Summary

Adds opt-in Shadow DOM support for content scripts, providing CSS/DOM isolation so host page styles don't affect the extension UI and vice versa.

• Resolves Can the style isolation of Google extensions be integrated into the framework? #1142
• Related tracking issue for CSS HMR edge cases: Shadow DOM: CSS HMR support for content scripts #1143

Motivation

Content scripts inject UI directly into the host page's DOM, which means the host page's CSS can unintentionally break extension styles (and vice versa). Shadow DOM provides a native browser isolation boundary. While users can create shadow DOM manually, making Vite's CSS injection and HMR work inside shadow DOM requires patching Vite client internals — which CRXJS already does for other purposes.

How it works

Configuration

// vite.config.ts — global opt-in
crx({
  manifest,
  contentScripts: { shadowDom: true }        // open mode (default)
  // or: contentScripts: { shadowDom: { mode: 'closed' } }
})

Per-script override via __crx_shadowDom field in the manifest (stripped from output).

Content script API

// content.ts
import './style.css'

export function onExecute({ shadowRoot }: ContentScriptAPI.ExecuteFnOptions) {
  const app = document.createElement('div')
  app.innerHTML = `<h1>Isolated UI</h1>`
  shadowRoot.appendChild(app)
}

Production (build)

• Shadow loader creates <crx-root> element, attaches shadow root
• CSS loaded via adoptedStyleSheets using fetch() + CSSStyleSheet.replaceSync()
• CSS files automatically added to web_accessible_resources
• Uses a placeholder mechanism so CSS output filenames are resolved after Vite's build manifest is available (during renderCrxManifest)

Development (serve)

• Shadow loader sets globalThis.__CRX_SHADOW_ROOT__ before importing the content script
• Patches HTMLHeadElement.prototype.appendChild/removeChild to redirect <style data-vite-dev-id> elements to the shadow root
• Patches Document.prototype.querySelector so Vite can find existing styles in the shadow root for HMR deduplication
• CSS HMR works without full page reload

Scope

• Only affects ISOLATED world content scripts (MAIN world scripts are unaffected)
• No portal helper utilities — users handle React/framework portals themselves

Changes

New files

File	Description
src/client/iife/content-dev-loader-shadow.ts	Dev mode shadow DOM IIFE loader
src/client/iife/content-pro-loader-shadow.ts	Production shadow DOM IIFE loader
tests/e2e/mv3-vite-vanilla-content-script-shadow-dom/	Full E2E test suite

Modified files

File	Description
src/node/types.ts	Added shadowDom to CrxOptions.contentScripts
src/node/contentScripts.ts	Added shadowDom/shadowMode to ContentScript interface, shadow loader factories, CSS placeholder
src/node/plugin-contentScripts.ts	Three-way branching (MAIN / shadow / regular) for loader creation
src/node/plugin-manifest.ts	Shadow DOM resolution from config + per-script override, stripping from output
src/node/plugin-fileWriter-polyfill.ts	CSS shadow root redirection patches for dev mode
src/node/plugin-contentScripts_css.ts	Shadow DOM scripts skip manifest CSS injection; post-processes shadow loader assets to replace CSS placeholder with actual URLs
src/node/plugin-webAccessibleResources.ts	Shadow DOM CSS files added to WAR for fetch() access
client.d.ts	Added shadowRoot to ExecuteFnOptions

Testing

E2E tests cover:

• Build: Shadow root created, content rendered, extension CSS applied inside shadow DOM
• Build: Host page CSS (!important via MAIN world script) does NOT penetrate shadow boundary
• Serve: Shadow DOM renders correctly, CSS isolation works
• Serve: CSS HMR updates inside shadow DOM without page reload
• Serve: Host page <h1> stays styled by MAIN world script after HMR

Full suite results:

• 120 passed, 4 skipped, 1 pre-existing flaky failure (unrelated seq-hmr 100ms timeout)
• Zero regressions

[changeset-bot]

🦋 Changeset detected

Latest commit: a7b4914

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@crxjs/vite-plugin	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[nizoio]

a small nice thing to have is the ability to change "crx-root" name through the settings:

crx({
  manifest,
 contentScripts: { shadowDom: { mode: 'open', wrapper: "crxjs-custom-root" } }
});

@Toumash also just wanted to ask why this hasn't been merged yet 🤔?

[Toumash]

@nizoio review needed. Not super strict as that is a opt-in feature, but still + broken ci test to be fixed/investigated

[Toumash]

ok so the test works

[nizoio]

I tested this PR using patch-package, but I ran into a strange development bug: Shadow DOM style changes don’t apply on the first attempt for some reason (updates are always one step behind HMR changes).

For example, changing a Vue component’s styles from:

.button { background: red; }

doesn’t work.

If I then change it again to:

.button { background: blue; }

the button turns red (not blue).

it is always one change behind.

It seems like there’s a timing issue somewhere. I’m no expert in this, but I spent some time trying to figure out the root cause but no luck 😬

@Toumash any idea why this is happening? 🤔

[Toumash]

@nizoio i'll create a vue e2e test then and we'll see

[Toumash]

@nizoio updated the test and fix

[salmin89]

If you set

contentScripts: { shadowDom: true }

will this only affect content scripts that export onExecute?