Add Hook to Control CSS Injection for Dynamically Imported Modules in Web Components with Shadow DOM

[r-Larch]

Description:

As a developer using Vite to build Web Components with Shadow DOM, I need to control where dynamically imported CSS is injected. Currently, CSS from dynamic imports is always injected into document.head by the __vitePreload function, but in cases like Web Components using Shadow DOM, the CSS needs to be injected into the shadow root.

When dynamically importing modules, such as:

const FlowSlider = lazy(() => import("../flows/views/FlowSlider"));

The generated code includes a __vitePreload function that loads all the associated dependencies, including CSS. However, the CSS is injected into document.head, as seen in the following part of the code:

document.head.appendChild(link); // Injects CSS into document.head

This behavior is problematic for Web Components using Shadow DOM, where styles need to be scoped within the shadow root and not globalized by being inserted into the document’s head.

Suggested solution:

To solve this issue, I suggest adding an option or a hook to control where the CSS <link> elements created by __vitePreload are appended. Ideally, this should allow the developer to register some kind of listener to receive the dependency URL and perform the preload.

For example, import.meta.registerPreloadDependency could be used to allow developers to register a listener for handling the preloading process:

import { customElement } from "solid-element";

// create Web Component with Shadow DOM and use `StylesLoader` to load styles into the shadow root.
customElement("my-widget", (props) => {
  return (
    <StylesLoader>
      foobar
    </StylesLoader>
  );
});

function StylesLoader(props) {
  let stylesContainer: HTMLDivElement;

  // Register a listener for preloading dependencies
  import.meta.registerPreloadDependency(preloadDependency);

  function preloadDependency(dep: string): Promise<void> | undefined {
    const isCss = dep.endsWith(".css");
    const link = document.createElement("link");
    link.rel = isCss ? "stylesheet" : "modulepreload";
    link.href = dep;
    stylesContainer.appendChild(link);
    if (isCss) {
      return new Promise((res, rej) => {
        link.addEventListener("load", res);
        link.addEventListener("error", () =>
          rej(new Error(`Unable to preload CSS for ${dep}`))
        );
      });
    }
  }

  return (
    <>
      <div ref={(el) => (stylesContainer = el)} />
      {props.children}
    </>
  );
}

Alternative:

Without this feature, developers like myself must manually move the <link> elements from document.head to the shadow root, which is neither scalable nor clean.

Additional context:

This feature would be especially useful for developers building Web Components using Shadow DOM, where encapsulated styles are critical for maintaining the integrity of component styling. It would also benefit other use cases where developers need to scope styles to a specific part of the DOM, rather than having them applied globally via document.head.

[sapphi-red]

I think this is similar to #11855.

About the suggested solution, I'm not sure how to make it work with multiple shadow roots.
For example,

// element.js
import './foo.css' // where will this CSS be registered, both custom elements? or the global window?
import './common.js'

export function customElement1() {
  //
}

export function customElement2() {
  //
}

// common.js
import './common.css' // also this CSS

[r-Larch]

The imports like import './foo.css' and import './common.js' (with subsequent import './common.css') typically end up in a separate file like dist/assets/main-ASDd23d.css and can be manually loaded into the shadow DOM. For handling these, I rely on dist/.vite/manifest.json.

However, my concern is specifically with dynamic imports and the default behavior of __vitePreload. The issue arises because I cannot override the way __vitePreload handles CSS injected through dynamic imports, which always goes to document.head. I’m looking for a way to control this behavior so I can inject styles into the shadow root instead.

[sapphi-red]

I see. To make sure, using import style from './foo.css?inline' or import cssUrl from './foo.css?url' is not an option for you, am I right?

[r-Larch]

That's right, it's not really an option for me.
With ?inline or ?url I would need to ensure all components down the tree are managing there styles manually, but that's impossible because of shared components and 3th party components and styles in dynamic imports would still be challenging.

[r-Larch]

I think the only way to handle this feature effectively is through a combination of a Vite configuration option and a code design guideline.

The listener for handling the preloading process (in this case, something like import.meta.registerPreloadDependency(listener: (dep: string) => Promise<void>)) relies on a clear separation between the Web Component wrapper and the actual Widget component implementation. This ensures that registerPreloadDependency is called before any dynamic imports are triggered in the component.

Example Project Setup

├── src
│   ├── widgets
│   │   ├── views
│   │   │   ├── DynamicComponent.tsx
│   │   ├── Widget1.tsx
│   │   ├── Widget2.tsx
│   ├── index.tsx

In this setup, we separate the Web Component wrapper (responsible for registering the preloading listener) from the actual widget logic (which contains dynamic imports). This ensures that styles for dynamically imported components are properly loaded into the correct shadow root.

index.tsx

import { customElement } from "solid-element";

// Widgets will have dynamic imports
import Widget1 from "./widgets/Widget1";
import Widget2 from "./widgets/Widget2";

// Create Web Component with Shadow DOM and use `StylesLoader` to load styles into the shadow root.
customElement("my-widget-1", (props) => {
  return (
    <StylesLoader>
      <Widget1 />
    </StylesLoader>
  );
});

// Create Web Component with Shadow DOM and use `StylesLoader` to load styles into the shadow root.
customElement("my-widget-2", (props) => {
  return (
    <StylesLoader>
      <Widget2 />
    </StylesLoader>
  );
});

function StylesLoader(props) {
  let stylesContainer: HTMLDivElement;

  // Register a listener for preloading dependencies
  import.meta.registerPreloadDependency(preloadDependency);

  function preloadDependency(dep: string): Promise<void> | undefined {
    const isCss = dep.endsWith(".css");
    const link = document.createElement("link");
    link.rel = isCss ? "stylesheet" : "modulepreload";
    link.href = dep;
    stylesContainer.appendChild(link);
    if (isCss) {
      return new Promise((res, rej) => {
        link.addEventListener("load", res);
        link.addEventListener("error", () =>
          rej(new Error(`Unable to preload CSS for ${dep}`))
        );
      });
    }
  }

  return (
    <>
      <div ref={(el) => (stylesContainer = el)} />
      {props.children}
    </>
  );
}

Widget1.tsx

The actual widget components (Widget1.tsx and Widget2.tsx) contain dynamic imports. These imports will be handled by the preloading listener registered in the Web Component wrapper (StylesLoader) to ensure styles are injected into the correct shadow root.

// DynamicComponent will have CSS dependencies
// The `import` and `__vitePreload` will only run when rendering.
const DynamicComponent = lazy(() => import("./views/DynamicComponent"));

export default function Widget1(props) {
  return (
    <div>
      {/* Now __vitePreload will run */}
      <DynamicComponent />
    </div>
  );
}

Why This Separation Matters

The important point here is the separation of the Web Component wrapper and the actual Widget component implementation. By ensuring that import.meta.registerPreloadDependency is called in the Web Component wrapper (before any dynamic imports are triggered in the Widget component), you can guarantee that the preloading listener is in place before Vite attempts to load any CSS dependencies dynamically.

This separation ensures that the CSS from dynamically imported components is correctly scoped to the shadow DOM of each Web Component.

How It Works

For all widgets, the listener is registered before any dynamic imports are triggered. This means that each Web Component wrapper (like my-widget-1 and my-widget-2) can handle its own dynamically imported styles through the registered listener.

The challenge is how __vitePreload manages multiple listeners. There are two potential approaches here:

1. Call All Registered Listeners:
   When __vitePreload is triggered, it can call all listeners, which would ensure that CSS files are loaded into every Web Component that needs them. While this might result in a bit of redundancy, it's a relatively simple and effective solution, and the cost of loading the same CSS into different shadow roots isn’t too high.

2. Clever Listener Matching:
   A more complex solution would involve __vitePreload identifying the correct listener based on the context (e.g., which Web Component triggered the dynamic import). This could involve attaching some kind of metadata or scope to each listener and the __vitePreload call, so it knows which component's styles need to be injected. However, this approach could introduce significant complexity and may require changes to how import.meta.registerPreloadDependency and dynamic imports are tracked.

Additionally, __vitePreload would need to manage its seen collection per listener rather than globally. This would ensure that the same CSS file can be preloaded into multiple shadow roots as needed, without being blocked by the global seen collection.

Summary

• Solution 1: Simply call all registered listeners for every dynamic import. This would ensure that the relevant styles are loaded into all Web Components, though at the cost of potential redundancy.

• Solution 2: Implement a more complex system to track which listener (or Web Component) triggered the dynamic import, allowing for more precise CSS injection but at the cost of increased complexity.

In either case, the seen collection needs to be handled per listener to avoid preloading issues across multiple shadow roots.