Runtime fetch() for styles breaks with bundlers

[DmitrySharabin]

Summary

nude-element loads shadow DOM styles at runtime via fetch(). Each element class declares a static property (e.g., static styles = "./my-slider.css") and at runtime the library resolves the full URL, fetches the CSS text, creates a CSSStyleSheet, and adopts it onto the shadow root.

This breaks with all bundlers in production (CSS files are never emitted, so fetch() 404s), and additionally in Vite's dev server (which serves .css as JS modules).

The issue affects all five static style properties that go through the defineStyles() → fetch() path: styles, shadowStyles, globalStyles, lightStyles, and documentStyles.

Bundler	Dev server	Production build
Vite	❌ Wrong Content-Type	❌ CSS not emitted
webpack	✅ Works	❌ CSS not emitted
Rollup / esbuild	✅ Works (no dev server)	❌ CSS not emitted
Parcel	✅ Likely works	❌ CSS not emitted

Root Cause

static styles = "./my-slider.css" is an opaque string literal — not an ES import. No bundler tracks it as a dependency, so the .css files are never emitted to the output directory.

The fetch() path in code

1. Class setup — first_constructor_static hook in src/plugins/styles/base.js calls this.defineStyles(this.styles).
2. defineStyles() — if the value is a string, wraps it as { url: string } and resolves the full URL.
3. connected hook — calls adoptStyle(options, roots) from src/plugins/styles/util/adopt-style.js.
4. adoptStyle() — three branches:
   • ref instanceof CSSStyleSheet → use directly
   • ref.css → new CSSStyleSheet() + replaceSync(css) ✅
   • URL fallback → cachedFetch(fullUrl) → fetch() ❌ breaks with bundlers

The { css: string } branch bypasses fetch() entirely, which is why inlining CSS at build time works.

Possible Solutions

1. import with CSS module attributes — Use import "./foo.css" with {type: "css"} which bundlers can track as a dependency. Supported almost everywhere except Safari, but could be used with a fetch() fallback for unsupported browsers. A helper function could detect support and use either method accordingly.

2. Document the { css } pattern as the recommended approach for bundled projects (already works, zero library changes needed).

3. Ship an official Vite plugin as a package (e.g., nude-element/vite). A proof-of-concept plugin that rewrites style string literals into ?inline CSS imports (which Vite resolves as plain CSS strings):

   function inlineShadowStyles() {
     const RE = /\bstatic\s+(styles|shadowStyles|globalStyles|lightStyles|documentStyles)\s*=\s*(['"])(\.\/[^'"]+\.css)\2/g;
   
     return {
       name: "inline-shadow-styles",
       transform(code, id) {
         if (!id.endsWith(".js")) return null;
   
         RE.lastIndex = 0;
         if (!RE.test(code)) return null;
         RE.lastIndex = 0;
   
         const imports = [];
         let i = 0;
         const newCode = code.replace(RE, (_match, prop, _quote, cssPath) => {
           const varName = `__shadow_styles_${i++}`;
           imports.push(`import ${varName} from "${cssPath}?inline";`);
           return `static ${prop} = [{ css: ${varName} }]`;
         });
   
         return { code: imports.join("\n") + "\n" + newCode, map: null };
       },
     };
   }

   This handles all five static style properties and works for both dev and production builds.

[LeaVerou]

This is now exceedingly long and would benefit with a summary, as it seems to be about different issues. We should probably open separate issues and keep this one focused on the first one (fetching styles)

I would strongly prefer to avoid Vite plugins and the like.
For CSS, which seems to be the main fetch() need, what about this:

• import "./foo.css" with {type: "css"} works almost everywhere except Safari, but most importantly, it's supported by bundlers (I think). With a dynamic import() we can use it in a try .. catch or with a .catch().
• If bundlers are not used, fetch() will work fine

What if we have a little helper function that detects whether CSS import attributes are supported and uses either method accordingly? If bundlers can read that properly, they'd presumably resolve it before it hits browsers.

[LeaVerou]

I would strongly prefer to avoid Vite plugins and the like.
For CSS, which seems to be the main fetch() need, what about this:

• import "./foo.css" with {type: "css"} works almost everywhere except Safari, but most importantly, it's supported by bundlers (I think). With a dynamic import() we can use it in a try .. catch or with a .catch().
• If bundlers are not used, fetch() will work fine

What if we have a little helper function that detects whether CSS import attributes are supported and uses either method accordingly? If bundlers can read that properly, they'd presumably resolve it before it hits browsers.

The following analysis is from Claude (AI assistant), not from @LeaVerou:

The idea is partially sound, but there's a critical gap worth flagging.

What works:

• import(url, {with: {type: "css"}}) as a direct call with a literal string IS statically analyzable by bundlers — they'd track it as a CSS dependency. ✓
• The existing adoptStyle() already handles Promise (it recursively unwraps them), so accepting a promise from component authors is mostly a matter of also handling the module namespace (.default) when unwrapping. ✓
• The try/catch / .catch() for runtime Safari fallback would work — {with: {type: "css"}} is just a plain object property name so it won't cause a parse error anywhere, and browsers that don't support CSS module scripts will throw a catchable error. ✓

The gap:

A helper function won't solve the bundler problem. Bundlers analyze import() calls statically — they can't see through an arbitrary function that wraps one. So if component authors write:

static styles = cssImport("./my-slider.css", import.meta.url); // bundler sees nothing

...bundlers still don't track the CSS file. The helper function idea only works for the browser side (runtime detection), not for the bundler side.

For bundler support, component authors would need to write the import() directly:

static styles = import("./my-slider.css", {with: {type: "css"}});

That's a real API change (no longer a plain string), but it actually would work with bundlers without any plugin.

The fetch fallback wrinkle:

When the import rejects, the library needs the original URL to fall back to fetch() — but it doesn't have it at that point. One option is to push that onto component authors:

static styles = import("./my-slider.css", {with: {type: "css"}})
  .then(m => m.default)
  .catch(() => new URL("./my-slider.css", import.meta.url).href);

...but that's quite verbose. Alternatively, the library could just not bother with a fetch fallback for this path — if you're writing import() with a literal path, you probably care about bundler compat, and if your browser doesn't support CSS module scripts in 2025+, that's increasingly rare.

Bottom line: The approach works if the API change is "write import(...) directly, not a string path". The helper function idea is useful for runtime fallback but doesn't help bundlers. Worth exploring whether that API change is acceptable — it would eliminate the need for any Vite plugin.

[DmitrySharabin]

Experiment: CSS Import Attributes as a plugin-free bundler solution

I experimented with CSS Import Attributes (import ... with { type: "css" }) as a way to fix the bundler issue without a Vite plugin.

Key finding: you cannot fix this in nude-element alone. The static styles = "./foo.css" string is just a string at runtime — by that point the bundler has already broken things:

• Vite dev: serves .css as a JS HMR module (wrong content-type for fetch())
• Vite build: never emits the file as a standalone asset (404)

There's nothing the library can do to recover from a string it receives after the bundler has acted.

What CSS Import Attributes require (and what actually works):

The import must appear statically in the component source:

// color-swatch.js
import swatchStyles from "./color-swatch.css" with { type: "css" };

static styles = swatchStyles;

The library needs to handle this on its end — add two branches in defineStyles() in base.js before the typeof === "string" check:

for (let options of def) {
    if (options instanceof Promise) {
        // Dynamic: import("./foo.css", { with: { type: "css" } })
        options = { css: options.then(m => m.default ?? m), ...defaultOptions };
    }
    else if (options instanceof CSSStyleSheet) {
        // Static: import styles from "./foo.css" with { type: "css" }
        options = { css: options, ...defaultOptions };
    }
    else if (typeof options === "string") {
        options = { url: options, ...defaultOptions };
    }
    // ...

Both the { css: Promise<CSSStyleSheet> } and { css: CSSStyleSheet } cases are already handled downstream by cssToSheet() in adopt-style.js, so no further changes needed there.

The two options in practice:

Approach	Component syntax	Touches components?	Bundler config?
Dynamic import	static styles = import("./x.css", {with:{type:"css"}})	Yes	No
Static import	import s from "./x.css" with {type:"css"}; static styles = s	Yes	No
Existing Vite plugin	static styles = "./x.css" (unchanged)	No	Yes

The base.js change is additive and backward-compatible — existing string paths continue to work for non-bundled use. But component authors must opt in to the import-attribute syntax for bundler compatibility; the library cannot do it for them.

[DmitrySharabin]

A helper function approach is worth considering, but unfortunately it runs into a fundamental constraint: bundlers work by statically analysing source code at build time, before anything runs in the browser.

A helper that receives a URL string at runtime:

function loadStyles(url) {
    if (cssImportAttributesSupported()) {
        return import(url, { with: { type: "css" } });
    }
    return fetch(url).then(r => r.text());
}

...would give the bundler a dynamic import with a dynamic URL. It can't statically resolve which file to include, so the CSS asset still never gets emitted — same breakage as before.

What bundlers need to see is a static string literal at the import site:

import swatchStyles from "./color-swatch.css" with { type: "css" };

That's what lets Vite/Rollup/esbuild trace the dependency and process the file correctly. By the time any runtime detection could run, the bundler has already decided what's in the bundle.

[LeaVerou]

From what I'm reading, most modern bundlers recognize new URL("./my-element.css", import.meta.url) as asset URLs, as long as the path is static (not an expression or variable). So perhaps we could move towards using that? It's a little noisy, but not the end of the world

[DmitrySharabin]

Tested @LeaVerou's suggestion with new URL("./foo.css", import.meta.url) in Vite. A few findings:

Library changes needed (both in base.js/cached-fetch.js):

1. defineStyles() needs an instanceof URL branch → { url: url.href }
2. cachedFetch() needs to handle data: URIs — Vite inlines small assets (< 4 KB) as base64 data URIs by default, and fetch() doesn't support them. Fix: decode directly via atob() instead of calling fetch().

Component side: must use import.meta.url literally — this.url doesn't work because Vite's static analyzer requires the exact new URL(..., import.meta.url) pattern to recognize the asset.

Dev mode: still broken. Vite serves .css files as JS HMR modules, so fetch() gets JS, not CSS. The old Vite plugin solved this; new URL() doesn't help here.

[LeaVerou]

One we have a getStyle() helper like I suggested in #92, we can also detect whether the environment supports CSS modules and use `import(url, {with: {type: "css"}}) if so which may solve this. We could even detect JS modules and fetch as a regular module.