feat: add config-loader cli option

sxzz · sxzz · commit f0ef73143741 · 2025-09-12T02:31:09.000+09:00
closes #479
diff --git a/docs/options/config-file.md b/docs/options/config-file.md
@@ -62,6 +62,17 @@ tsdown --no-config
 
 This is useful if you want to rely solely on command-line options or default settings.
 
+## Config Loaders
+
+`tsdown` supports multiple config loaders to accommodate various file formats. You can select a config loader using the `--config-loader` option. The available loaders are:
+
+- `auto` (default): Utilizes native runtime loading for TypeScript if supported; otherwise, defaults to `unconfig`.
+- `native`: Loads TypeScript configuration files using native runtime support. Requires a compatible environment, such as the latest Node.js, Deno, or Bun.
+- `unconfig`: Loads configuration files with the `unconfig` library, ensuring broad compatibility across different runtimes.
+
+> [!TIP]
+> Node.js does not natively support importing TypeScript files without specifying the file extension. If you are using Node.js and want to load a TypeScript config file without including the `.ts` extension, consider using the `unconfig` loader for seamless compatibility.
+
 ## Extending Vite or Vitest Config (Experimental)
 
 `tsdown` provides an **experimental** feature to extend your existing Vite or Vitest configuration files. This allows you to reuse specific configuration options, such as `resolve` and `plugins`, while ignoring others that are not relevant to `tsdown`.
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
@@ -18,6 +18,12 @@ Specify a custom configuration file. Use this option to define the path to the c
 
 See also [Config File](../options/config-file.md).
 
+## `--config-loader <loader>`
+
+Specifies which config loader to use.
+
+See also [Config File](../options/config-file.md).
+
 ## `--no-config`
 
 Disable loading a configuration file. This is useful if you want to rely solely on command-line options or default settings.
diff --git a/docs/zh-CN/options/config-file.md b/docs/zh-CN/options/config-file.md
@@ -62,6 +62,17 @@ tsdown --no-config
 
 这在您希望仅依赖命令行选项或默认设置时非常有用。
 
+## 配置加载器
+
+`tsdown` 支持多种配置加载器，以适配不同的文件格式。您可以通过 `--config-loader` 选项选择配置加载器。可用的加载器包括：
+
+- `auto`（默认）：如果运行时支持，则使用原生方式加载 TypeScript，否则回退到 `unconfig`。
+- `native`：通过原生运行时支持加载 TypeScript 配置文件。需要兼容的环境，如最新版 Node.js、Deno 或 Bun。
+- `unconfig`：使用 `unconfig` 库加载配置文件，确保在不同运行时下具有广泛兼容性。
+
+> [!TIP]
+> Node.js 原生不支持在不指定文件扩展名的情况下导入 TypeScript 文件。如果您在 Node.js 环境下希望加载不带 `.ts` 扩展名的 TypeScript 配置文件，建议使用 `unconfig` 加载器以获得更好的兼容性。
+
 ## 扩展 Vite 或 Vitest 配置（实验性功能）{#extending-vite-or-vitest-config-experimental}
 
 `tsdown` 提供了一个**实验性**功能，允许您扩展现有的 Vite 或 Vitest 配置文件。通过此功能，您可以复用特定的配置选项（如 `resolve` 和 `plugins`），同时忽略与 `tsdown` 无关的其他选项。
diff --git a/docs/zh-CN/reference/cli.md b/docs/zh-CN/reference/cli.md
@@ -18,6 +18,12 @@ tsdown src/index.ts src/util.ts
 
 另请参阅 [配置文件](../options/config-file.md)。
 
+## `--config-loader <loader>`
+
+指定要使用的配置加载器。
+
+另请参阅 [配置文件](../options/config-file.md)。
+
 ## `--no-config`
 
 禁用加载配置文件。如果您希望仅依赖命令行选项或默认设置，此选项非常有用。
diff --git a/src/cli.ts b/src/cli.ts
@@ -17,6 +17,11 @@ cli
     allowUnknownOptions: true,
   })
   .option('-c, --config <filename>', 'Use a custom config file')
+  .option(
+    '--config-loader <loader>',
+    'Config loader to use: auto, native, unconfig',
+    { default: 'auto' },
+  )
   .option('--no-config', 'Disable config file')
   .option('-f, --format <format>', 'Bundle format: esm, cjs, iife, umd', {
     default: 'esm',
diff --git a/src/options/config.ts b/src/options/config.ts
@@ -77,8 +77,18 @@ export async function loadConfigFile(
     }
   }
 
-  const nativeTS =
-    process.features.typescript || process.versions.bun || process.versions.deno
+  let isNative = false
+  if (!loaded) {
+    if (!options.configLoader || options.configLoader === 'auto') {
+      isNative = !!(
+        process.features.typescript ||
+        process.versions.bun ||
+        process.versions.deno
+      )
+    } else if (options.configLoader === 'native') {
+      isNative = true
+    }
+  }
 
   let { config, sources } = await loadConfig
     .async<UserConfig | UserConfigFn>({
@@ -88,14 +98,7 @@ export async function loadConfigFile(
             {
               files: 'tsdown.config',
               extensions: ['ts', 'mts', 'cts', 'js', 'mjs', 'cjs', 'json', ''],
-              parser:
-                loaded || !nativeTS
-                  ? 'auto'
-                  : async (filepath) => {
-                      const mod = await import(pathToFileURL(filepath).href)
-                      const config = mod.default || mod
-                      return config
-                    },
+              parser: isNative ? nativeImport : 'auto',
             },
             {
               files: 'package.json',
@@ -126,3 +129,20 @@ export async function loadConfigFile(
     file,
   }
 }
+
+async function nativeImport(id: string) {
+  const mod = await import(pathToFileURL(id).href).catch((error) => {
+    const cannotFindModule = error?.message?.includes?.('Cannot find module')
+    if (cannotFindModule) {
+      const configError = new Error(
+        `Failed to load the config file. Try setting the --config-loader CLI flag to \`unconfig\`.\n\n${error.message}`,
+      )
+      configError.cause = error
+      throw configError
+    } else {
+      throw error
+    }
+  })
+  const config = mod.default || mod
+  return config
+}
diff --git a/src/options/types.ts b/src/options/types.ts
@@ -351,6 +351,12 @@ export interface Options {
    */
   config?: boolean | string
 
+  /**
+   * Config loader to use. It can only be set via CLI or API.
+   * @default 'auto'
+   */
+  configLoader?: 'auto' | 'native' | 'unconfig'
+
   /**
    * Reuse config from Vite or Vitest (experimental)
    * @default false
@@ -454,7 +460,9 @@ export interface Options {
 /**
  * Options without specifying config file path.
  */
-export type UserConfig = Arrayable<Omit<Options, 'config' | 'filter'>>
+export type UserConfig = Arrayable<
+  Omit<Options, 'config' | 'filter' | 'configLoader'>
+>
 export type UserConfigFn = (cliOptions: Options) => Awaitable<UserConfig>
 export type NormalizedUserConfig = Exclude<UserConfig, any[]>
 
@@ -470,6 +478,7 @@ export type ResolvedOptions = Omit<
         | 'logLevel'
         | 'failOnWarn'
         | 'customLogger'
+        | 'configLoader'
       >,
       | 'globalName'
       | 'inputOptions'
