feat(es): Add jsc.preserveSymlinks to swc::Options (#11813)

## Description

Wires the `NodeImportResolver::with_config_preserving_symlinks`
constructor (added in #11801) through to `swc::Options` as a new
`jsc.preserveSymlinks` boolean config option. When enabled:

- `ModuleConfig::get_resolver` skips the `base.canonicalize()` call on
the input file, so the input path is left at its symlink location.
- `build_resolver` constructs the `NodeImportResolver` via the new
preserve-symlinks constructor, so rewritten module specifiers don't
re-canonicalize target paths.
- The `build_resolver` memoization key is extended with
`preserve_symlinks` so the two modes don't share cached resolver
instances.

Default behaviour is unchanged — canonicalization still happens unless
the flag is explicitly set.

## Motivation

Monorepos that symlink shared source files (e.g. `shared/foo.ts`
symlinked into `packages/app-a/src/foo.ts` and
`packages/app-b/src/foo.ts`) break under the current behaviour: once any
link is followed to the real path, relative imports inside `shared/`
resolve against the real parent directory rather than the importing
package, producing module-not-found errors.

`resolve.symlinks: false` at the bundler level (rspack, webpack) is not
enough if the downstream transformer re-canonicalizes. This PR is the
upstream companion to web-infra-dev/rspack#13762, which exposes a
`preserveSymlinks` option on `builtin:swc-loader` once this lands.

## Test

`crates/swc/tests/preserve_symlinks.rs` (new) exercises the full
`swc::Options` pipeline against a tempdir with the shape:

```
root/
  src/index.ts      // import "../server/source";
  shared/source.ts  // export const value = 1;
  server/source.ts  // symlink -> ../shared/source.ts
```

It asserts that:

- With `jsc.preserveSymlinks = false` (default): the rewritten specifier
is `"../shared/source"` (canonicalized).
- With `jsc.preserveSymlinks = true`: the rewritten specifier remains
`"../server/source"` (symlink preserved).

The existing low-level coverage in
`crates/swc_ecma_transforms_module/tests/path_node.rs::symlink_paths_are_preserved_only_when_opted_in`
is unchanged.

## Related issue:

Closes #11584

Author: perbergland

.changeset/cool-lanterns-preserve.md

@@ -0,0 +1,6 @@
+---
+swc: major
+swc_core: minor
+---
+
+feat(es): add `jsc.preserveSymlinks` option to opt out of symlink canonicalization in the module transform resolver

Cargo.lock

@@ -147,6 +147,7 @@ ansi_term                 = { workspace = true }
 codspeed-criterion-compat = { workspace = true }
 criterion                 = { workspace = true }
 par-core                  = { workspace = true, features = ["chili"] }
+tempfile                  = { workspace = true }
 walkdir                   = { workspace = true }
 
 swc_ecma_ast = { version = "23.0.0", path = "../swc_ecma_ast", features = [

crates/swc/Cargo.toml

@@ -306,10 +306,12 @@ impl Options {
             lints,
             preserve_all_comments,
             rewrite_relative_import_extensions,
+            preserve_symlinks,
             ..
         } = cfg.jsc;
         let loose = loose.into_bool();
         let preserve_all_comments = preserve_all_comments.into_bool();
+        let preserve_symlinks = preserve_symlinks.into_bool();
         let keep_class_names = keep_class_names.into_bool();
         let external_helpers = external_helpers.into_bool();
 
@@ -590,7 +592,13 @@ impl Options {
         };
 
         let paths = paths.into_iter().collect();
-        let resolver = ModuleConfig::get_resolver(&base_url, paths, base, cfg.module.as_ref());
+        let resolver = ModuleConfig::get_resolver(
+            &base_url,
+            paths,
+            base,
+            cfg.module.as_ref(),
+            preserve_symlinks,
+        );
 
         let target = es_version;
         let inject_helpers = !self.skip_helper_injection;
@@ -1391,6 +1399,17 @@ pub struct JscConfig {
     /// https://www.typescriptlang.org/tsconfig/#rewriteRelativeImportExtensions
     #[serde(default)]
     pub rewrite_relative_import_extensions: BoolConfig<false>,
+
+    /// When `true`, symlinked paths are preserved in generated module
+    /// specifiers instead of being canonicalized to their real paths.
+    ///
+    /// This is the config-level analogue of Node's `--preserve-symlinks`.
+    /// Enable it when your project relies on symlinked source files (for
+    /// example, a monorepo that symlinks shared sources into each package)
+    /// and you want relative imports inside those files to continue to
+    /// resolve against their symlinked location rather than the real path.
+    #[serde(default)]
+    pub preserve_symlinks: BoolConfig<false>,
 }
 
 #[derive(Debug, Default, Clone, Serialize, Deserialize, Merge)]
@@ -1604,6 +1623,7 @@ impl ModuleConfig {
         paths: CompiledPaths,
         base: &FileName,
         config: Option<&ModuleConfig>,
+        preserve_symlinks: bool,
     ) -> Option<(FileName, Arc<dyn ImportResolver>)> {
         let skip_resolver = base_url.as_os_str().is_empty() && paths.is_empty();
 
@@ -1612,46 +1632,57 @@ impl ModuleConfig {
         }
 
         let base = match base {
-            FileName::Real(v) if !skip_resolver => {
+            FileName::Real(v) if !skip_resolver && !preserve_symlinks => {
                 FileName::Real(v.canonicalize().unwrap_or_else(|_| v.to_path_buf()))
             }
             _ => base.clone(),
         };
 
         let base_url = base_url.to_path_buf();
         let resolver = match config {
-            None => build_resolver(base_url, paths, false, &util::Config::default_js_ext()),
+            None => build_resolver(
+                base_url,
+                paths,
+                false,
+                &util::Config::default_js_ext(),
+                preserve_symlinks,
+            ),
             Some(ModuleConfig::Es6(config)) | Some(ModuleConfig::NodeNext(config)) => {
                 build_resolver(
                     base_url,
                     paths,
                     config.config.resolve_fully,
                     &config.config.out_file_extension,
+                    preserve_symlinks,
                 )
             }
             Some(ModuleConfig::CommonJs(config)) => build_resolver(
                 base_url,
                 paths,
                 config.resolve_fully,
                 &config.out_file_extension,
+                preserve_symlinks,
             ),
             Some(ModuleConfig::Umd(config)) => build_resolver(
                 base_url,
                 paths,
                 config.config.resolve_fully,
                 &config.config.out_file_extension,
+                preserve_symlinks,
             ),
             Some(ModuleConfig::Amd(config)) => build_resolver(
                 base_url,
                 paths,
                 config.config.resolve_fully,
                 &config.config.out_file_extension,
+                preserve_symlinks,
             ),
             Some(ModuleConfig::SystemJs(config)) => build_resolver(
                 base_url,
                 paths,
                 config.config.resolve_fully,
                 &config.config.out_file_extension,
+                preserve_symlinks,
             ),
         };
 
@@ -1680,6 +1711,7 @@ impl ModuleConfig {
         _paths: CompiledPaths,
         _base: &FileName,
         _config: Option<&ModuleConfig>,
+        _preserve_symlinks: bool,
     ) -> Option<(FileName, Arc<dyn swc_ecma_loader::resolve::Resolve>)> {
         None
     }
@@ -1997,9 +2029,10 @@ fn build_resolver(
     paths: CompiledPaths,
     resolve_fully: bool,
     file_extension: &str,
+    preserve_symlinks: bool,
 ) -> SwcImportResolver {
     static CACHE: Lazy<
-        DashMap<(PathBuf, CompiledPaths, bool, String), SwcImportResolver, FxBuildHasher>,
+        DashMap<(PathBuf, CompiledPaths, bool, String, bool), SwcImportResolver, FxBuildHasher>,
     > = Lazy::new(Default::default);
 
     // On Windows, we need to normalize path as UNC path.
@@ -2021,6 +2054,7 @@ fn build_resolver(
         paths.clone(),
         resolve_fully,
         file_extension.to_owned(),
+        preserve_symlinks,
     )) {
         return cached.clone();
     }
@@ -2037,19 +2071,27 @@ fn build_resolver(
         let r = TsConfigResolver::new(r, base_url.clone(), paths.clone());
         let r = CachingResolver::new(256, r);
 
-        let r = NodeImportResolver::with_config(
-            r,
-            modules::path::Config {
-                base_dir: Some(base_url.clone()),
-                resolve_fully,
-                file_extension: file_extension.to_owned(),
-            },
-        );
+        let cfg = modules::path::Config {
+            base_dir: Some(base_url.clone()),
+            resolve_fully,
+            file_extension: file_extension.to_owned(),
+        };
+        let r = if preserve_symlinks {
+            NodeImportResolver::with_config_preserving_symlinks(r, cfg)
+        } else {
+            NodeImportResolver::with_config(r, cfg)
+        };
         Arc::new(r)
     };
 
     CACHE.insert(
-        (base_url, paths, resolve_fully, file_extension.to_owned()),
+        (
+            base_url,
+            paths,
+            resolve_fully,
+            file_extension.to_owned(),
+            preserve_symlinks,
+        ),
         r.clone(),
     );
 

crates/swc/src/config/mod.rs

@@ -0,0 +1,122 @@
+//! Integration test for `jsc.preserveSymlinks`.
+//!
+//! Exercises the full `swc::Options` pipeline against a symlinked source file,
+//! mirroring the low-level check in
+//! `swc_ecma_transforms_module::tests::path_node::symlink_paths_are_preserved_only_when_opted_in`.
+use std::{
+    fs::{create_dir_all, write},
+    path::Path,
+};
+
+use swc::{
+    config::{Config, IsModule, JscConfig, ModuleConfig, Options},
+    Compiler,
+};
+use swc_common::FileName;
+use swc_ecma_parser::{Syntax, TsSyntax};
+use tempfile::tempdir;
+use testing::Tester;
+
+fn create_symlink(target: &Path, link: &Path) {
+    #[cfg(unix)]
+    {
+        std::os::unix::fs::symlink(target, link).unwrap();
+    }
+
+    #[cfg(windows)]
+    {
+        std::os::windows::fs::symlink_file(target, link).unwrap();
+    }
+}
+
+fn setup_symlink_fixture(root: &Path) {
+    create_dir_all(root.join("src")).unwrap();
+    create_dir_all(root.join("shared")).unwrap();
+    create_dir_all(root.join("server")).unwrap();
+
+    write(root.join("src/index.ts"), "import \"../server/source\";\n").unwrap();
+    write(root.join("shared/source.ts"), "export const value = 1;\n").unwrap();
+
+    create_symlink(
+        &root.join("shared/source.ts"),
+        &root.join("server/source.ts"),
+    );
+}
+
+fn options_for(root: &Path, preserve_symlinks: bool) -> Options {
+    Options {
+        swcrc: false,
+        filename: root.join("src/index.ts").display().to_string(),
+        config: Config {
+            jsc: JscConfig {
+                syntax: Some(Syntax::Typescript(TsSyntax::default())),
+                base_url: root.to_path_buf(),
+                preserve_symlinks: preserve_symlinks.into(),
+                ..Default::default()
+            },
+            module: Some(ModuleConfig::Es6(Default::default())),
+            is_module: Some(IsModule::Bool(true)),
+            ..Default::default()
+        },
+        ..Default::default()
+    }
+}
+
+fn compile(index_path: &Path, options: Options) -> String {
+    let source = std::fs::read_to_string(index_path).unwrap();
+    let index_path = index_path.to_path_buf();
+
+    Tester::new()
+        .print_errors(|cm, handler| {
+            let c = Compiler::new(cm.clone());
+
+            let fm = cm.new_source_file(FileName::Real(index_path.clone()).into(), source.clone());
+            let result = c.process_js_file(fm, &handler, &options);
+
+            match result {
+                Ok(v) if !handler.has_errors() => Ok(v.code),
+                _ => Err(()),
+            }
+        })
+        .unwrap()
+}
+
+#[test]
+fn preserve_symlinks_default_canonicalizes_import() {
+    let sandbox = tempdir().unwrap();
+    let root = sandbox.path().canonicalize().unwrap();
+
+    setup_symlink_fixture(&root);
+
+    let options = options_for(&root, false);
+    let code = compile(&root.join("src/index.ts"), options);
+
+    assert!(
+        code.contains("../shared/source"),
+        "default should canonicalize to the real path; got:\n{code}"
+    );
+    assert!(
+        !code.contains("../server/source"),
+        "default must not leave the symlink path in the output; got:\n{code}"
+    );
+}
+
+#[test]
+fn preserve_symlinks_opt_in_keeps_symlink_import() {
+    let sandbox = tempdir().unwrap();
+    let root = sandbox.path().canonicalize().unwrap();
+
+    setup_symlink_fixture(&root);
+
+    let options = options_for(&root, true);
+    let code = compile(&root.join("src/index.ts"), options);
+
+    assert!(
+        code.contains("../server/source"),
+        "preserveSymlinks=true should keep the symlink path; got:\n{code}"
+    );
+    assert!(
+        !code.contains("../shared/source"),
+        "preserveSymlinks=true must not canonicalize the target; got:\n{code}"
+    );
+}