feat: add opt-in CommonJS default interop for Node ESM

README.md

@@ -40,9 +40,39 @@ export default defineConfig({
 
 ## API
 
-| Option    | Description                                              |
-| --------- | -------------------------------------------------------- |
-| `plugins` | Register `@rc-component/father-plugin` in father config. |
+### Default imports in native ESM
+
+`cjsDefaultInterop` is **off by default**. When omitted or `false`, the plugin does not register the interop transformer or load its inspection dependencies; existing compiler output and import semantics are preserved.
+
+Opt in for a package that needs transpiled CommonJS defaults to work in native Node ESM. With Father 4.6.37 or newer:
+
+```ts | pure
+import type {} from '@rc-component/father-plugin';
+import { defineConfig } from 'father';
+
+export default defineConfig({
+  plugins: ['@rc-component/father-plugin'],
+  cjsDefaultInterop: true,
+  esm: { platform: 'node', autoExtension: true },
+});
+```
+
+The type-only import enables the plugin's configuration types for `defineConfig`; it emits no runtime import. The switch is a top-level plugin option, separate from `esm` and `cjs`. Changing it also changes Father's per-file build cache key.
+
+When enabled, the plugin normalizes default imports from statically identifiable transpiled CommonJS dependencies in **Node ESM output only**. It resolves each package's Node **import** entry, then checks for `__esModule` and `default` exports without executing the dependency. Package names are not hardcoded: scoped packages, package subpaths, and statically identifiable CommonJS re-export entries are supported.
+
+Father keeps its default esbuild compiler for Node. The same output normalization also works with explicitly selected Babel or SWC, after their TypeScript/JSX transforms. Source maps are composed back to the original source. One small helper is generated per affected output file, so component source keeps ordinary default imports, including `import { default as Name }`.
+
+Entries identified as native ESM at build time and plain CommonJS exports stay unchanged. The rule skips named imports, namespace imports, type-only imports, relative imports, builtins, dynamic imports, and dependency re-export statements in the consuming source. Unresolved dependencies, unrecognized export structures, and output syntax unsupported by the inspection parser are left untouched. Browser-targeted and CommonJS builds keep their existing compiler output.
+
+**Enabling this option changes default-import semantics.** For a recognized CommonJS dependency, `import pkg from 'legacy'` receives its inner `default` value instead of the CommonJS exports object. Code that already calls `pkg.default()` or reads other properties of that object must be reviewed before enabling it. If a downstream resolver selects a native ESM entry after the build identified the dependency as CommonJS, the generated local variable captures the initial value; subsequent updates to that default export are not reflected. The runtime check does not preserve ESM live bindings in this case. Validate the package's supported consumers before opting in.
+
+This is a compatibility bridge until dependencies expose native ESM entries. Generated code still checks the loaded value at runtime. The parsing and resolution dependencies run only during the library build; no helper package is imported by the generated output.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `plugins` | — | Register `@rc-component/father-plugin` in father config. |
+| `cjsDefaultInterop` | `false` | Opt in to CommonJS default-import normalization for Node ESM output. |
 
 ## Development
 

README.zh-CN.md

@@ -40,9 +40,39 @@ export default defineConfig({
 
 ## API
 
-| 名称      | 说明                                                 |
-| --------- | ---------------------------------------------------- |
-| `plugins` | 在 father 配置中注册 `@rc-component/father-plugin`。 |
+### 原生 ESM 的默认导入
+
+`cjsDefaultInterop` **默认关闭**。不配置或设为 `false` 时，插件不注册 interop 编译处理，也不加载相关检查依赖，保留原有编译产物和导入语义。
+
+需要让转译后的 CommonJS 默认导入在原生 Node ESM 中工作时，由组件库显式开启。使用 Father 4.6.37 或更高版本：
+
+```ts | pure
+import type {} from '@rc-component/father-plugin';
+import { defineConfig } from 'father';
+
+export default defineConfig({
+  plugins: ['@rc-component/father-plugin'],
+  cjsDefaultInterop: true,
+  esm: { platform: 'node', autoExtension: true },
+});
+```
+
+类型导入为 `defineConfig` 加载插件的配置类型，不产生运行时导入。开关位于配置顶层，与 `esm`、`cjs` 同级。切换开关也会改变 Father 的文件构建缓存键。
+
+开启后，仅对 **Node ESM 产物** 中能静态识别的转译后 CommonJS 依赖处理默认导入。插件按照 Node 的 **import** 条件解析依赖入口，检查 `__esModule` 和 `default` 导出，全程不执行依赖代码。不维护包名白名单，支持带 scope 的包、包子路径和可静态识别的 CommonJS 转导出入口。
+
+Father 继续使用 Node 平台默认的 esbuild；显式选择 Babel 或 SWC 时也会在 TypeScript/JSX 编译完成后执行相同的处理，并将 source map 合并回原始源码。每个涉及的产物文件只生成一个小型兼容函数，组件源码保持普通默认导入，包括 `import { default as Name }`。
+
+构建时识别为原生 ESM 的入口和普通 CommonJS 导出保持原样。规则不处理命名导入、命名空间导入、纯类型导入、相对路径、内置模块、动态导入以及消费方源码中的依赖再导出语句。无法解析的依赖、无法静态识别的导出结构以及检查用解析器不支持的产物语法也保持原样。面向浏览器的构建和 CommonJS 构建继续使用原有编译产物。
+
+**开启此选项会改变默认导入语义。** 对于识别到的 CommonJS 依赖，`import pkg from 'legacy'` 拿到的是内部的 `default` 值，原本的 CommonJS 导出对象会被解包。因此，已有的 `pkg.default()` 调用或对该对象其他属性的访问需要先检查。如果构建时识别为 CommonJS，下游实际却选择了原生 ESM 入口，生成的局部变量会保存初始值，无法反映默认导出的后续更新；运行时检查不能保留这种情况下的 ESM 实时绑定。组件库应验证其支持的消费方式后再开启。
+
+这是一项过渡措施，待依赖提供原生 ESM 入口后可移除。产物仍会在运行时检查导出值。解析相关依赖只在组件库构建时运行，产物不会额外导入 helper 包。
+
+| 名称 | 默认值 | 说明 |
+| --- | --- | --- |
+| `plugins` | — | 在 father 配置中注册 `@rc-component/father-plugin`。 |
+| `cjsDefaultInterop` | `false` | 显式开启 Node ESM 产物的 CommonJS 默认导入兼容处理。 |
 
 ## 本地开发
 

package.json

@@ -6,8 +6,10 @@
   "repository": "https://github.com/react-component/father-plugin.git",
   "license": "MIT",
   "main": "dist/index.js",
+  "types": "types.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "types.d.ts"
   ],
   "scripts": {
     "build": "father build",
@@ -37,14 +39,22 @@
     ]
   },
   "dependencies": {
-    "fs-extra": "^11.3.0"
+    "@ampproject/remapping": "^2.3.0",
+    "acorn": "^8.18.0",
+    "cjs-module-lexer": "^2.2.1",
+    "enhanced-resolve": "^5.24.5",
+    "fs-extra": "^11.3.0",
+    "magic-string": "^0.30.21"
   },
   "devDependencies": {
+    "@babel/core": "^7.29.7",
     "@commitlint/cli": "^21.2.0",
     "@commitlint/config-conventional": "^21.2.0",
     "@eslint/compat": "^2.1.0",
     "@eslint/js": "^10.0.1",
+    "@jridgewell/trace-mapping": "^0.3.31",
     "@rc-component/np": "^1.0.4",
+    "@swc/core": "^1.16.2",
     "@types/fs-extra": "^11.0.4",
     "eslint": "^10.6.0",
     "eslint-config-prettier": "^10.1.8",

src/defaultInterop.ts

@@ -0,0 +1,160 @@
+import remapping from '@ampproject/remapping';
+import { parse as parseModule } from 'acorn';
+import { parse as parseCommonJS } from 'cjs-module-lexer';
+import { create } from 'enhanced-resolve';
+import fs from 'fs';
+import MagicString from 'magic-string';
+import { builtinModules, createRequire } from 'module';
+import path from 'path';
+
+// Match Node's import branch, rather than accidentally inspecting a dual package's require entry.
+const resolveImport = create.sync({
+  conditionNames: ['node', 'import', 'default'],
+  mainFields: ['main'],
+  extensions: ['.js', '.json', '.node'],
+});
+
+function commonJSExports(
+  filename: string,
+  seen = new Set<string>(),
+): Set<string> {
+  if (seen.has(filename) || !/\.c?js$/.test(filename)) return new Set();
+  seen.add(filename);
+
+  try {
+    const { exports, reexports } = parseCommonJS(
+      fs.readFileSync(filename, 'utf8'),
+    );
+    const names = new Set(exports);
+    for (const request of reexports) {
+      try {
+        const dependency = createRequire(filename).resolve(request);
+        commonJSExports(dependency, seen).forEach((name) => names.add(name));
+      } catch {
+        // Optional or unresolved re-exports cannot be classified statically.
+      }
+    }
+    return names;
+  } catch {
+    // Native ESM and unrecognized syntax must keep their original import semantics.
+    return new Set();
+  }
+}
+
+function needsInterop(request: string, importer: string): boolean {
+  if (
+    /^(?:[./#]|[a-z][\w+.-]*:)/i.test(request) ||
+    builtinModules.includes(request)
+  )
+    return false;
+
+  try {
+    const entry = resolveImport(path.dirname(importer), request);
+    if (!entry) return false;
+    const names = commonJSExports(entry);
+    return names.has('__esModule') && names.has('default');
+  } catch {
+    return false;
+  }
+}
+
+/** Normalize statically identifiable transpiled CommonJS defaults after JS compilation. */
+export default function defaultInterop(
+  code: string,
+  importer: string,
+  sourceMap?: string | null,
+): [string, (string | null)?] {
+  const names = new Set<string>();
+  let program: ReturnType<typeof parseModule>;
+  try {
+    program = parseModule(code, {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      allowHashBang: true,
+      onToken(token) {
+        if (
+          token.type.label === 'name' &&
+          'value' in token &&
+          typeof token.value === 'string'
+        ) {
+          names.add(token.value);
+        }
+      },
+    });
+  } catch {
+    // Do not reject compiler output whose syntax this inspection parser cannot handle.
+    return [code, sourceMap];
+  }
+  const uid = (name: string) => {
+    let candidate = `_${name}`;
+    while (names.has(candidate)) candidate += '_';
+    names.add(candidate);
+    return candidate;
+  };
+  const helper = uid('rcDefaultInterop');
+  const output = new MagicString(code);
+  const declarations: string[] = [];
+
+  for (const statement of program.body) {
+    if (statement.type !== 'ImportDeclaration') continue;
+    const defaults = statement.specifiers.filter(
+      (specifier) =>
+        specifier.type === 'ImportDefaultSpecifier' ||
+        (specifier.type === 'ImportSpecifier' &&
+          (specifier.imported.type === 'Identifier'
+            ? specifier.imported.name
+            : specifier.imported.value) === 'default'),
+    );
+    if (
+      !defaults.length ||
+      !needsInterop(String(statement.source.value), importer)
+    )
+      continue;
+
+    for (const specifier of defaults) {
+      const imported = uid(`${specifier.local.name}Module`);
+      output.overwrite(specifier.local.start, specifier.local.end, imported);
+      declarations.push(
+        `var ${specifier.local.name} = ${helper}(${imported});`,
+      );
+    }
+  }
+
+  if (!declarations.length) return [code, sourceMap];
+
+  let insertion = code.startsWith('#!') ? code.indexOf('\n') + 1 : 0;
+  for (const statement of program.body) {
+    if (statement.type !== 'ExpressionStatement' || !statement.directive) break;
+    insertion = statement.end;
+  }
+  // TODO: Remove the bridge when the dependencies expose native ESM entries.
+  // Imports are hoisted; initialize aliases before any original executable statement.
+  output.appendLeft(
+    insertion,
+    `
+function ${helper}(value) {
+  return value && (typeof value === 'object' || typeof value === 'function') &&
+    value.__esModule && 'default' in value ? value.default : value;
+}
+${declarations.join('\n')}
+`,
+  );
+
+  const map = sourceMap
+    ? remapping(
+        [
+          {
+            version: 3,
+            ...output.generateDecodedMap({
+              source: importer,
+              includeContent: true,
+              hires: true,
+            }),
+          },
+          sourceMap,
+        ],
+        () => null,
+      ).toString()
+    : sourceMap;
+  return [output.toString(), map];
+}

src/index.ts

@@ -1,6 +1,7 @@
 import { execSync } from 'child_process';
 import type { IApi } from 'father';
 import fs from 'fs-extra';
+import { createRequire } from 'module';
 import path from 'path';
 
 const cwd = process.cwd();
@@ -41,8 +42,33 @@ function checkNpmPackageDependency(packageJson: any, packageName: string) {
 }
 
 export default (api: IApi) => {
+  // Keep this separate from the shared plugin: false must only disable interop.
+  api.registerPlugins([
+    {
+      id: 'virtual: rc-cjs-default-interop',
+      key: 'cjsDefaultInterop',
+      config: {
+        default: false,
+        schema: (joi: any) => joi.boolean().strict(),
+      },
+    },
+  ]);
+
   // Compile break if export type without consistent
   api.onStart(async () => {
+    if (
+      api.config.cjsDefaultInterop === true &&
+      (api.name === 'build' || api.name === 'dev')
+    ) {
+      // Father 4 collects addJSTransformer before loading project plugins.
+      // Register after initialization, against the project's actual Father instance.
+      const projectRequire = createRequire(path.join(api.cwd, 'package.json'));
+      const { addTransformer } = projectRequire('father/dist/builder/bundless');
+      for (const id of ['babel', 'esbuild', 'swc']) {
+        addTransformer({ id, transformer: require.resolve('./transformer') });
+      }
+    }
+
     if (api.name !== 'build') {
       return;
     }
@@ -60,8 +86,7 @@ export default (api: IApi) => {
       process.exit(1);
     }
 
-    const inputFolder =
-      api?.config?.esm?.input || api?.config?.esm?.input || 'src/';
+    const inputFolder = api.config.esm?.input || 'src/';
 
     const isEslintInstalled = checkNpmPackageDependency(packageJson, 'eslint');
     if (isEslintInstalled) {

src/transformer.ts

@@ -0,0 +1,23 @@
+import type { IFatherConfig, IJSTransformer } from 'father';
+import { createRequire } from 'module';
+import path from 'path';
+import defaultInterop from './defaultInterop';
+
+type Transformer = NonNullable<IJSTransformer['fn']>;
+
+// Delegate to Father's compiler so its JSX, aliases, targets, and source maps stay in effect.
+const transformer: Transformer = async function (content) {
+  const { config, paths } = this;
+  const loadCompiler = createRequire(path.join(paths.cwd, 'package.json'));
+  const compile = loadCompiler(
+    `father/dist/builder/bundless/loaders/javascript/${config.transformer}`,
+  ).default;
+  const result = await compile.call(this, content);
+  return (config as IFatherConfig).cjsDefaultInterop === true &&
+    config.format === 'esm' &&
+    config.platform === 'node'
+    ? defaultInterop(result[0], paths.fileAbsPath, result[1])
+    : result;
+};
+
+export default transformer;