feat!: config loader default to 'auto' (#1240)

Timeless0911 · fi3ework · web-flow · commit 7674ab621ef1 · 2025-09-23T15:05:54.000+08:00
Co-authored-by: Wei &lt;fi3ework@gmail.com&gt;
diff --git a/packages/core/src/cli/commands.ts b/packages/core/src/cli/commands.ts
@@ -43,9 +43,9 @@ const applyCommonOptions = (cli: CAC) => {
     )
     .option(
       '--config-loader <loader>',
-      'Set the config file loader (jiti | native)',
+      'Set the config file loader (auto | jiti | native)',
       {
-        default: 'jiti',
+        default: 'auto',
       },
     )
     .option('--env-dir <dir>', 'specify the directory to load `.env` files')
diff --git a/packages/core/src/config.ts b/packages/core/src/config.ts
@@ -119,7 +119,7 @@ const resolveConfigPath = (root: string, customConfig?: string): string => {
   throw new Error(`${DEFAULT_CONFIG_NAME} not found in ${root}`);
 };
 
-export type ConfigLoader = 'jiti' | 'native';
+export type ConfigLoader = 'auto' | 'jiti' | 'native';
 
 export async function loadConfig({
   cwd = process.cwd(),
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/tests/integration/cli/build/build.test.ts b/tests/integration/cli/build/build.test.ts
@@ -82,7 +82,7 @@ describe('build command', async () => {
     `);
   });
 
-  test('--config-loader', async () => {
+  test('should use Node.js native loader to load config', async () => {
     // Skip Node.js <= 22.18
     if (!process.features.typescript) {
       return;
@@ -103,6 +103,21 @@ describe('build command', async () => {
     `);
   });
 
+  test('should fallback to jiti when --config-loader set to auto which is default strategy', async () => {
+    await fse.remove(path.join(__dirname, 'dist-auto'));
+    runCliSync('build --config rslib.config.auto.mts', {
+      cwd: __dirname,
+    });
+
+    const files = await globContentJSON(path.join(__dirname, 'dist-auto'));
+    const fileNames = Object.keys(files).sort();
+    expect(fileNames).toMatchInlineSnapshot(`
+      [
+        "<ROOT>/tests/integration/cli/build/dist-auto/index.js",
+      ]
+    `);
+  });
+
   test('--root', async () => {
     await fse.remove(path.join(__dirname, 'dist'));
     runCliSync('build --root custom-root', {
diff --git a/tests/integration/cli/build/path.json b/tests/integration/cli/build/path.json
@@ -0,0 +1,3 @@
+{
+  "distPath": "dist-auto"
+}
diff --git a/tests/integration/cli/build/rslib.config.auto.mts b/tests/integration/cli/build/rslib.config.auto.mts
@@ -0,0 +1,15 @@
+import { defineConfig } from '@rslib/core';
+import { generateBundleEsmConfig } from 'test-helper';
+import distPathJson from './path.json';
+
+export default defineConfig({
+  lib: [
+    generateBundleEsmConfig({
+      output: {
+        distPath: {
+          root: distPathJson.distPath,
+        },
+      },
+    }),
+  ],
+});
diff --git a/website/docs/en/guide/basic/cli.mdx b/website/docs/en/guide/basic/cli.mdx
@@ -29,7 +29,7 @@ Rslib CLI provides several common flags that can be used with all commands:
 | Flag                       | Description                                                                                                                                                 |
 | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `-c, --config <config>`    | Specify the configuration file, can be a relative or absolute path, see [Specify config file](/guide/basic/configure-rslib#specify-config-file)             |
-| `--config-loader <loader>` | Set the config file loader (`jiti` \| `native`), see [Specify config loader](/guide/basic/configure-rslib#specify-config-loader)                            |
+| `--config-loader <loader>` | Set the config file loader (`auto` \| `jiti` \| `native`), see [Specify config loader](/guide/basic/configure-rslib#specify-config-loader)                  |
 | `--env-dir <dir>`          | Specify the directory to load `.env` files, see [Rsbuild - Env directory](https://rsbuild.rs/guide/advanced/env-vars#env-directory)                         |
 | `--env-mode <mode>`        | Specify the env mode to load the `.env.[mode]` file, see [Rsbuild - Env mode](https://rsbuild.rs/guide/advanced/env-vars#env-mode)                          |
 | `-h, --help`               | Display help for command                                                                                                                                    |
diff --git a/website/docs/en/guide/basic/configure-rslib.mdx b/website/docs/en/guide/basic/configure-rslib.mdx
@@ -127,21 +127,42 @@ rslib build -c rslib.prod.config.mjs
 
 ## Specify config loader
 
-When you use a configuration file with the `.ts`, `.mts`, and `.cts` extensions, Rslib will use [jiti](https://github.com/unjs/jiti) to load configuration files, providing interoperability between ESM and CommonJS. The behavior of module resolution differs slightly from the native behavior of Node.js.
+Rslib provides three ways to load configuration files:
 
-If your JavaScript runtime already natively supports TypeScript, you can use the `--config-loader native` option to use the Node.js native loader to load the configuration file. This can ensure that the module resolution behavior is consistent with the native behavior of Node.js and has better performance.
+- `jiti`: When you use a configuration file with the `.ts`, `.mts`, and `.cts` extensions, Rslib will use [jiti](https://github.com/unjs/jiti) to load configuration files, providing interoperability between ESM and CommonJS. The behavior of module resolution differs slightly from the native behavior of Node.js.
+- `native`: Use Node.js native loader to load the configuration file. This can ensure that the module resolution behavior is consistent with the native behavior of Node.js and has better performance. This requires that your JavaScript runtime already natively supports TypeScript.
 
-For example, Node.js v22.6.0+ already natively supports TypeScript, you can use the following command to use the Node.js native loader to load the configuration file:
+  For example, Node.js v22.6.0+ already natively supports TypeScript, you can use the following command to use the Node.js native loader to load the configuration file:
 
-```bash
-# Node.js >= v22.18.0
-# No need to set --experimental-strip-types
-npx rslib build --config-loader native
+  ```bash
+  # Node.js >= v22.18.0
+  # No need to set --experimental-strip-types
+  npx rslib build --config-loader native
 
-# Node.js v22.6.0 - v22.17.0
-# Need to set --experimental-strip-types
-NODE_OPTIONS="--experimental-strip-types" npx rslib build --config-loader native
-```
+  # Node.js v22.6.0 - v22.17.1
+  # Need to set --experimental-strip-types
+  NODE_OPTIONS="--experimental-strip-types" npx rslib build --config-loader native
+  ```
+
+- `auto`(Default): Use Node.js's native loader to load configuration files first, fallback to using jiti if it fails.
+
+### About Node.js native loader
+
+When using Node.js's native loader, please note the following limitations:
+
+1. When importing JSON files, you need to use import attributes:
+
+   ```ts
+   import pkgJson from './package.json' with { type: 'json' }; // ✅ Correct
+   import pkgJson from './package.json'; // ❌ Incorrect
+   ```
+
+2. When importing TypeScript files, you need to include the `.ts` extension:
+
+   ```ts
+   import baseConfig from './rslib.base.config.ts'; // ✅ Correct
+   import baseConfig from './rslib.base.config'; // ❌ Incorrect
+   ```
 
 > See [Node.js - Running TypeScript Natively](https://nodejs.org/en/learn/typescript/run-natively#running-typescript-natively) for more details.
 
diff --git a/website/docs/zh/guide/basic/cli.mdx b/website/docs/zh/guide/basic/cli.mdx
@@ -29,7 +29,7 @@ Rslib CLI 提供了一些公共选项，可以用于所有命令：
 | 选项                       | 描述                                                                                                                      |
 | -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
 | `-c, --config <config>`    | 指定配置文件路径，可以为相对路径或绝对路径，详见 [指定配置文件](/guide/basic/configure-rslib#指定配置文件)                |
-| `--config-loader <loader>` | 指定配置文件加载方式（`jiti` \| `native`），详见 [指定加载方式](/guide/basic/configure-rslib#指定加载方式)                |
+| `--config-loader <loader>` | 指定配置文件加载方式（`auto` \| `jiti` \| `native`），详见 [指定加载方式](/guide/basic/configure-rslib#指定加载方式)      |
 | `--env-dir <dir>`          | 指定目录来加载 `.env` 文件，详见 [Rsbuild - Env 目录](https://rsbuild.rs/zh/guide/advanced/env-vars#env-目录)             |
 | `--env-mode <mode>`        | 指定 env 模式来加载 `.env.[mode]` 文件，详见 [Rsbuild - Env 模式](https://rsbuild.rs/zh/guide/advanced/env-vars#env-模式) |
 | `-h, --help`               | 显示命令帮助                                                                                                              |
diff --git a/website/docs/zh/guide/basic/configure-rslib.mdx b/website/docs/zh/guide/basic/configure-rslib.mdx
@@ -127,21 +127,42 @@ rslib build -c rslib.prod.config.mjs
 
 ## 指定加载方式
 
-当你使用 `.ts`, `.mts` 和 `.cts` 后缀的配置文件时，Rslib 会使用 [jiti](https://github.com/unjs/jiti) 来加载配置文件，提供 ESM 与 CommonJS 的互操作性，模块解析的行为与 Node.js 原生行为存在一定差异。
+Rslib 提供了三种配置文件加载方式：
 
-如果你使用的 JavaScript 运行时已经原生支持 TypeScript，可以使用 `--config-loader native` 选项来使用 Node.js 原生 loader 来加载配置文件。这可以保证模块解析的行为与 Node.js 原生行为一致，并且性能更好。
+- `jiti`：当你使用 `.ts`, `.mts` 和 `.cts` 后缀的配置文件时，Rslib 会使用 [jiti](https://github.com/unjs/jiti) 来加载配置文件，提供 ESM 与 CommonJS 的互操作性，模块解析的行为与 Node.js 原生行为存在一定差异。
+- `native`：使用 Node.js 原生 loader 来加载配置文件，这可以保证模块解析的行为与 Node.js 原生行为一致，并且性能更好。这要求你使用的 JavaScript 运行时已经原生支持 TypeScript。
 
-例如，Node.js 从 v22.6.0 开始已经原生支持 TypeScript，你可以如下命令来使用 Node.js 原生 loader 来加载配置文件：
+  例如，Node.js 从 v22.6.0 开始已经原生支持 TypeScript，你可以运行如下命令来使用 Node.js 原生 loader 来加载配置文件：
 
-```bash
-# Node.js >= v22.18.0
-# 不需要设置 --experimental-strip-types
-npx rslib build --config-loader native
+  ```bash
+  # Node.js >= v22.18.0
+  # 不需要设置 --experimental-strip-types
+  npx rslib build --config-loader native
 
-# Node.js v22.6.0 - v22.17.0
-# 需要设置 --experimental-strip-types
-NODE_OPTIONS="--experimental-strip-types" npx rslib build --config-loader native
-```
+  # Node.js v22.6.0 - v22.17.1
+  # 需要设置 --experimental-strip-types
+  NODE_OPTIONS="--experimental-strip-types" npx rslib build --config-loader native
+  ```
+
+- `auto`（默认）：优先使用 Node.js 原生 loader 来加载配置文件，失败时回退到使用 jiti 加载。
+
+### 关于 Node.js 原生 loader
+
+使用 Node.js 原生 loader 时，请注意以下限制：
+
+1. 导入 JSON 文件时，需要使用 import attributes：
+
+   ```ts
+   import pkgJson from './package.json' with { type: 'json' }; // ✅ 正确
+   import pkgJson from './package.json'; // ❌ 错误
+   ```
+
+2. 导入 TypeScript 文件时，需要包含 `.ts` 扩展名：
+
+   ```ts
+   import baseConfig from './rslib.base.config.ts'; // ✅ 正确
+   import baseConfig from './rslib.base.config'; // ❌ 错误
+   ```
 
 > 详见 [Node.js - Running TypeScript Natively](https://nodejs.org/en/learn/typescript/run-natively#running-typescript-natively)。
 

Original file line number	Diff line number	Diff line change
`@@ -43,9 +43,9 @@ const applyCommonOptions = (cli: CAC) => {`
`43`	`43`	`)`
`44`	`44`	`.option(`
`45`	`45`	`'--config-loader <loader>',`
`46`		`- 'Set the config file loader (jiti \| native)',`
	`46`	`+ 'Set the config file loader (auto \| jiti \| native)',`
`47`	`47`	`{`
`48`		`- default: 'jiti',`
	`48`	`+ default: 'auto',`
`49`	`49`	`},`
`50`	`50`	`)`
`51`	`51`	.option('--env-dir <dir>', 'specify the directory to load `.env` files')
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "distPath": "dist-auto"`
	`3`	`+}`