fix(esm-library): handle CSS modules in preserveModules

CSS modules (native `experiments.css` or mini-css-extract) under
`output.library.preserveModules` caused either "chunk xxx should have at
least one file" or "Multiple assets emit different content to the same
filename". preserveModules set the JS filename_template on CSS chunks,
left chunks nameless so multiple CSS files collapsed onto `.css`, and
the ESM render phase emitted `import "__RSPACK_ESM_CHUNK_<id>"`
placeholders pointing at CSS-only chunks with no JS file.

Classify modules in preserve_modules by source_types and set
css_filename_template for CSS modules (preserving the `.css` extension
and source path), skip CSS-only modules/chunks in the ESM render paths
that emit JS-side requires / cross-chunk imports, and make
CssExtractRspackPlugin honor chunk.css_filename_template so preserveModules
can override its per-chunk filename.

Author: JSerFeng

crates/rspack_plugin_esm_library/src/preserve_modules.rs

@@ -1,16 +1,12 @@
-use std::{borrow::Cow, path::Path, sync::LazyLock};
+use std::path::{Path, PathBuf};
 
-use regex::Regex;
 use rspack_collections::{IdentifierMap, IdentifierSet};
-use rspack_core::Compilation;
+use rspack_core::{Compilation, Module, SourceType};
 use rspack_util::fx_hash::{FxHashMap, FxHashSet};
 use sugar_path::SugarPath;
 
 use crate::EsmLibraryPlugin;
 
-static EXTENSION_JS: LazyLock<Regex> =
-  LazyLock::new(|| Regex::new(r".+(\..+)$").expect("failed to compile EXTENSION_REGEXP"));
-
 pub fn entry_modules(compilation: &Compilation) -> FxHashMap<String, IdentifierSet> {
   let module_graph = compilation.get_module_graph();
   compilation
@@ -50,6 +46,42 @@ pub fn entry_name_for_module(
   entry_name_for_module
 }
 
+/// Returns whether a module should be processed by `preserve_modules`.
+/// Only JS and CSS modules are relevant — asset, wasm and other types are
+/// handled by their own output pipelines.
+fn should_preserve_module(module: &dyn Module, module_graph: &rspack_core::ModuleGraph) -> bool {
+  let source_types = module.source_types(module_graph);
+  if source_types.iter().any(|t| {
+    matches!(
+      t,
+      SourceType::JavaScript | SourceType::Css | SourceType::CssImport
+    )
+  }) {
+    return true;
+  }
+  // CSS modules created by the extract-css plugin use a `Custom` source type
+  // (`css/mini-extract`). Detect them by their identifier prefix to keep
+  // the dependency on `rspack_plugin_extract_css` out of this crate.
+  module.identifier().starts_with("css|")
+}
+
+/// Returns the absolute path of a module's resource, supporting both
+/// `NormalModule` and the synthetic `CssModule` from extract-css.
+fn module_resource_path(module: &dyn Module) -> Option<PathBuf> {
+  if let Some(normal_module) = module.as_normal_module() {
+    return normal_module
+      .resource_resolved_data()
+      .path()
+      .map(|p| p.as_std_path().to_path_buf());
+  }
+  // For non-normal modules (extract-css `CssModule`), derive the resource
+  // path from `name_for_condition`, which strips the loader chain and query
+  // string.
+  let name = module.name_for_condition()?;
+  let path = PathBuf::from(name.as_ref());
+  if path.is_absolute() { Some(path) } else { None }
+}
+
 pub async fn preserve_modules(
   root: &Path,
   compilation: &mut Compilation,
@@ -75,163 +107,172 @@ pub async fn preserve_modules(
       continue;
     }
 
-    let module_graph = compilation.get_module_graph();
-    let Some(normal_module) = module_graph
-      .module_by_identifier(&module_id)
-      .expect("should have module")
-      .as_normal_module()
-    else {
-      continue;
-    };
+    let abs_path = {
+      let module_graph = compilation.get_module_graph();
+      let module = module_graph
+        .module_by_identifier(&module_id)
+        .expect("should have module");
 
-    let Some(abs_path) = normal_module
-      .resource_resolved_data()
-      .path()
-      .map(|p| p.as_std_path())
-      .map(|p| p.to_path_buf())
-    else {
-      continue;
+      if !should_preserve_module(module.as_ref(), module_graph) {
+        continue;
+      }
+      let Some(abs_path) = module_resource_path(module.as_ref()) else {
+        continue;
+      };
+      abs_path
     };
+    if !abs_path.starts_with(root) {
+      continue;
+    }
+
     let chunk = match EsmLibraryPlugin::get_module_chunk(module_id, compilation) {
       Ok(c) => c,
       Err(e) => {
         errors.push(e.into());
         continue;
       }
     };
-    let old_chunk = compilation
-      .build_chunk_graph_artifact
-      .chunk_by_ukey
-      .expect_get_mut(&chunk);
-
-    if abs_path.starts_with(root) {
-      // split module into single chunk named root
-      let file_path = abs_path.relative(root);
-      let extension = file_path.extension();
-
-      let new_extension = old_chunk
-        .filename_template()
-        .unwrap_or(&compilation.options.output.filename)
-        .template()
-        .map_or(Cow::Borrowed(".js"), |tpl| {
-          if let Some(captures) = EXTENSION_JS.captures(tpl) {
-            Cow::Owned(captures[1].to_string())
-          } else {
-            Cow::Borrowed(".js")
-          }
-        });
-      let new_filename = if let Some(extension) = extension {
-        let ext_lossy = extension.to_string_lossy();
-        let file_path_lossy = file_path.to_string_lossy();
-        let suffix = format!(".{ext_lossy}");
-        let base = file_path_lossy
-          .strip_suffix(&suffix)
-          .unwrap_or(&file_path_lossy);
-        format!("{base}{new_extension}").into()
-      } else {
-        file_path.to_string_lossy().to_string().into()
-      };
 
-      let entry_name = if let Some(entry_names) = entry_name_for_module.get(&module_id) {
-        if entry_names.len() > 1 {
-          errors.push(
-            rspack_error::error!(
-              "{} is used in multiple entries: [{}], this is not allowed in preserveModules",
-              module_id,
-              entry_names
-                .iter()
-                .map(|s| s.as_str())
-                .collect::<Vec<_>>()
-                .join(", ")
-            )
-            .into(),
-          );
-          continue;
-        }
+    // Compute the `chunk.name` from the source path.
+    //
+    // Following Rollup's approach: strip the file extension and let the
+    // per-type output template add the correct one back. rspack has separate
+    // templates for each output type (`output.filename` → `[name].mjs` for
+    // JS, `output.cssFilename` → `[name].css` for CSS, etc.), so we always
+    // strip the source extension regardless of module type. This keeps
+    // preserve_modules completely type-agnostic for naming.
+    let file_path = abs_path.relative(root);
+    // `to_slash()` normalises to forward slashes on all platforms so chunk
+    // names (and the asset paths derived from them) stay consistent.
+    let file_path_str = file_path
+      .to_slash()
+      .expect("relative path should be valid UTF-8")
+      .into_owned();
+    let base_name: String = if let Some(extension) = file_path.extension() {
+      let suffix = format!(".{}", extension.to_string_lossy());
+      file_path_str
+        .strip_suffix(&suffix)
+        .unwrap_or(&file_path_str)
+        .to_string()
+    } else {
+      file_path_str
+    };
 
-        entry_names.iter().next().cloned()
-      } else {
-        None
-      };
+    let entry_name = if let Some(entry_names) = entry_name_for_module.get(&module_id) {
+      if entry_names.len() > 1 {
+        errors.push(
+          rspack_error::error!(
+            "{} is used in multiple entries: [{}], this is not allowed in preserveModules",
+            module_id,
+            entry_names
+              .iter()
+              .map(|s| s.as_str())
+              .collect::<Vec<_>>()
+              .join(", ")
+          )
+          .into(),
+        );
+        continue;
+      }
 
-      if compilation
+      entry_names.iter().next().cloned()
+    } else {
+      None
+    };
+
+    if compilation
+      .build_chunk_graph_artifact
+      .chunk_graph
+      .get_chunk_modules_identifier(&chunk)
+      .len()
+      == 1
+    {
+      // This is the last module in the chunk — rename in-place.
+      let old_chunk = compilation
         .build_chunk_graph_artifact
-        .chunk_graph
-        .get_chunk_modules_identifier(&chunk)
-        .len()
-        == 1
+        .chunk_by_ukey
+        .expect_get_mut(&chunk);
+      if let Some(old_name) = old_chunk.name().map(|s| s.to_string())
+        && old_name != base_name
       {
-        // this is last module in chunk, we can keep this chunk, just rename it
-        old_chunk.set_filename_template(Some(new_filename));
-        continue;
+        compilation
+          .build_chunk_graph_artifact
+          .named_chunks
+          .remove(&old_name);
       }
-
-      let new_chunk_ukey =
-        Compilation::add_chunk(&mut compilation.build_chunk_graph_artifact.chunk_by_ukey);
+      old_chunk.set_name(Some(base_name.clone()));
       compilation
         .build_chunk_graph_artifact
-        .chunk_graph
-        .add_chunk(new_chunk_ukey);
-      let [Some(new_chunk), Some(old_chunk)] = compilation
-        .build_chunk_graph_artifact
-        .chunk_by_ukey
-        .get_many_mut([&new_chunk_ukey, &chunk])
-      else {
-        unreachable!("new_chunk and old_chunk should be inserted already")
-      };
+        .named_chunks
+        .insert(base_name, chunk);
+      continue;
+    }
 
-      new_chunk.set_filename_template(Some(new_filename));
-      old_chunk.split(
-        new_chunk,
-        &mut compilation.build_chunk_graph_artifact.chunk_group_by_ukey,
-      );
-      // disconnect module from other chunks
+    let new_chunk_ukey =
+      Compilation::add_chunk(&mut compilation.build_chunk_graph_artifact.chunk_by_ukey);
+    compilation
+      .build_chunk_graph_artifact
+      .chunk_graph
+      .add_chunk(new_chunk_ukey);
+    let [Some(new_chunk), Some(old_chunk)] = compilation
+      .build_chunk_graph_artifact
+      .chunk_by_ukey
+      .get_many_mut([&new_chunk_ukey, &chunk])
+    else {
+      unreachable!("new_chunk and old_chunk should be inserted already")
+    };
+
+    new_chunk.set_name(Some(base_name.clone()));
+    old_chunk.split(
+      new_chunk,
+      &mut compilation.build_chunk_graph_artifact.chunk_group_by_ukey,
+    );
+    compilation
+      .build_chunk_graph_artifact
+      .named_chunks
+      .insert(base_name.clone(), new_chunk_ukey);
+
+    // disconnect module from other chunks
+    compilation
+      .build_chunk_graph_artifact
+      .chunk_graph
+      .disconnect_chunk_and_module(&chunk, module_id);
+
+    compilation
+      .build_chunk_graph_artifact
+      .chunk_graph
+      .connect_chunk_and_module(new_chunk_ukey, module_id);
+
+    if let Some(entry_name) = entry_name {
       compilation
         .build_chunk_graph_artifact
         .chunk_graph
-        .disconnect_chunk_and_module(&chunk, module_id);
+        .disconnect_chunk_and_entry_module(&chunk, module_id);
+
+      let entrypoint = compilation.entrypoint_by_name_mut(&entry_name);
+      let ukey = entrypoint.ukey;
+      entrypoint.set_entrypoint_chunk(new_chunk_ukey);
 
       compilation
         .build_chunk_graph_artifact
         .chunk_graph
-        .connect_chunk_and_module(new_chunk_ukey, module_id);
-
-      if let Some(entry_name) = entry_name {
-        compilation
-          .build_chunk_graph_artifact
-          .chunk_graph
-          .disconnect_chunk_and_entry_module(&chunk, module_id);
-
-        let entrypoint = compilation.entrypoint_by_name_mut(&entry_name);
-        let ukey = entrypoint.ukey;
-        entrypoint.set_entrypoint_chunk(new_chunk_ukey);
+        .connect_chunk_and_entry_module(new_chunk_ukey, module_id, ukey);
 
-        compilation
-          .build_chunk_graph_artifact
-          .chunk_graph
-          .connect_chunk_and_entry_module(new_chunk_ukey, module_id, ukey);
-
-        // Transfer the chunk name from the old entry chunk to the new chunk
-        // to avoid duplicate output filenames. Without this, the old chunk
-        // retains its entry name (e.g., "index") and if it has modules outside
-        // the root (which don't get a filename_template), its output falls back
-        // to `[name].mjs` → "index.mjs", conflicting with the new chunk's
-        // filename_template "index.mjs".
-        let old_chunk = compilation
-          .build_chunk_graph_artifact
-          .chunk_by_ukey
-          .expect_get_mut(&chunk);
-        if let Some(name) = old_chunk.name().map(|s| s.to_string()) {
-          old_chunk.set_name(None);
-          let new_chunk = compilation
-            .build_chunk_graph_artifact
-            .chunk_by_ukey
-            .expect_get_mut(&new_chunk_ukey);
-          new_chunk.set_name(Some(name.clone()));
+      // Remove the entry name from the old chunk to avoid filename conflicts.
+      // Without this, the old chunk retains its entry name (e.g. "index") and
+      // its output falls back to `[name].mjs` → "index.mjs", conflicting with
+      // the new chunk that already owns that name.
+      let old_chunk = compilation
+        .build_chunk_graph_artifact
+        .chunk_by_ukey
+        .expect_get_mut(&chunk);
+      if let Some(old_name) = old_chunk.name().map(|s| s.to_string()) {
+        old_chunk.set_name(None);
+        if old_name != base_name {
           compilation
             .build_chunk_graph_artifact
             .named_chunks
-            .insert(name, new_chunk_ukey);
+            .remove(&old_name);
         }
       }
     }