Document CSS module imports (`with { type: "css" }`) under --unstable-raw-imports

[bartlomieju]

Feature

CSS module imports landed in Deno via denoland/deno#35093 (behind the --unstable-raw-imports flag, towards denoland/deno#11961).

Importing a stylesheet with an import attribute now evaluates to a CSSStyleSheet, matching what Chrome and Firefox ship:

import sheet from "./styles.css" with { type: "css" };
console.log(sheet instanceof CSSStyleSheet);
for (const rule of sheet.cssRules) {
  console.log(rule.cssText);
}

Dynamic imports work too:

const { default: sheet } = await import("./styles.css", {
  with: { type: "css" },
});

The primary use case is running unmodified browser module graphs in Deno (SSR and testing of web components), where a CSS import currently kills module loading before any code runs.

What needs documenting

• How to enable the feature: --unstable-raw-imports flag (and the "unstable": ["raw-imports"] field in deno.json).
• Static and dynamic with { type: "css" } import syntax.
• The minimal CSSStyleSheet surface that Deno implements:
  • cssRules — returns a frozen array of CSSRule (not a live CSSRuleList); each access creates a fresh array.
  • replace(text) / replaceSync(text) — top-level @import rules are dropped (matching the CSSOM constructed-stylesheet behavior).
  • CSSRule.cssText — verbatim text of one top-level rule.
  • new CSSStyleSheet() constructor (constructor options like media/disabled/baseURL are not supported).
• Important limitations to call out:
  • Deno has no DOM, so a sheet can't be adopted anywhere; the implementation is backed by the raw CSS text.
  • cssRules uses a naive top-level rule split, not a real CSS parser/object model — methods like insertRule/deleteRule are not implemented.
  • Reading a CSS file requires read permission (--allow-read).
• Note the unstable status (API yet to be vetted; subject to change).

References

• Implementation PR: feat(unstable): CSS module imports (with { type: "css" }) deno#35093
• Tracking issue: Support CSS Modules deno#11961
• Spec: https://html.spec.whatwg.org/multipage/webappapis.html#css-module-script