Put native TS resolver for next config under --experimental-next-config-strip-types flag (#84675)

Using Node.js native TS resolution is great. However, enabling by
default can be frustrating for the users as it has restrictions, such as
requiring a file extension for imports, and does not read tsconfig.json
(no import alias).

It also emits a warning when using `next.config.ts` on a CommonJS
project, which is the majority of the apps:

```
(node:68710) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///.../next.config.ts is not specified and it doesn't parse as CommonJS.
Reparsing as ES module because module syntax was detected. This incurs a performance overhead.
To eliminate this warning, add "type": "module" to /.../package.json.
(Use `node --trace-warnings ...` to show where the warning was created)
```

Therefore, put this under an `--experimental-next-config-strip-types`
flag for now.

Author: devjiwonchoi

.github/workflows/build_and_test.yml

@@ -562,6 +562,7 @@ jobs:
     with:
       nodeVersion: ${{ matrix.node }}
       afterBuild: |
+        export __NEXT_NODE_NATIVE_TS_LOADER_ENABLED=true
         NEXT_TEST_MODE=dev NODE_OPTIONS=--experimental-transform-types node run-tests.js test/e2e/app-dir/next-config-ts-native-ts/**/*.test.ts test/e2e/app-dir/next-config-ts-native-mts/**/*.test.ts
       stepName: 'test-next-config-ts-native-ts-dev-${{ matrix.node }}'
 
@@ -582,6 +583,7 @@ jobs:
     with:
       nodeVersion: ${{ matrix.node }}
       afterBuild: |
+        export __NEXT_NODE_NATIVE_TS_LOADER_ENABLED=true
         NEXT_TEST_MODE=start NODE_OPTIONS=--experimental-transform-types node run-tests.js test/e2e/app-dir/next-config-ts-native-ts/**/*.test.ts test/e2e/app-dir/next-config-ts-native-mts/**/*.test.ts
       stepName: 'test-next-config-ts-native-ts-prod-${{ matrix.node }}'
 

packages/next/src/bin/next.ts

@@ -150,13 +150,20 @@ program
     '--experimental-upload-trace, <traceUrl>',
     'Reports a subset of the debugging trace to a remote HTTP URL. Includes sensitive data.'
   )
-  .action((directory: string, options: NextBuildOptions) =>
+  .option(
+    '--experimental-next-config-strip-types',
+    'Use Node.js native TypeScript resolution for next.config.(ts|mts)'
+  )
+  .action((directory: string, options: NextBuildOptions) => {
+    if (options.experimentalNextConfigStripTypes) {
+      process.env.__NEXT_NODE_NATIVE_TS_LOADER_ENABLED = 'true'
+    }
     // ensure process exits after build completes so open handles/connections
     // don't cause process to hang
-    import('../cli/next-build.js').then((mod) =>
+    return import('../cli/next-build.js').then((mod) =>
       mod.nextBuild(options, directory).then(() => process.exit(0))
     )
-  )
+  })
   .usage('[directory] [options]')
 
 program
@@ -208,8 +215,15 @@ program
     '--experimental-upload-trace, <traceUrl>',
     'Reports a subset of the debugging trace to a remote HTTP URL. Includes sensitive data.'
   )
+  .option(
+    '--experimental-next-config-strip-types',
+    'Use Node.js native TypeScript resolution for next.config.(ts|mts)'
+  )
   .action(
     (directory: string, options: NextDevOptions, { _optionValueSources }) => {
+      if (options.experimentalNextConfigStripTypes) {
+        process.env.__NEXT_NODE_NATIVE_TS_LOADER_ENABLED = 'true'
+      }
       const portSource = _optionValueSources.port
       import('../cli/next-dev.js').then((mod) =>
         mod.nextDev(options, portSource, directory)
@@ -267,11 +281,18 @@ program
       'Specify the maximum amount of milliseconds to wait before closing inactive connections.'
     ).argParser(parseValidPositiveInteger)
   )
-  .action((directory: string, options: NextStartOptions) =>
-    import('../cli/next-start.js').then((mod) =>
+  .option(
+    '--experimental-next-config-strip-types',
+    'Use Node.js native TypeScript resolution for next.config.(ts|mts)'
+  )
+  .action((directory: string, options: NextStartOptions) => {
+    if (options.experimentalNextConfigStripTypes) {
+      process.env.__NEXT_NODE_NATIVE_TS_LOADER_ENABLED = 'true'
+    }
+    return import('../cli/next-start.js').then((mod) =>
       mod.nextStart(options, directory)
     )
-  )
+  })
   .usage('[directory] [options]')
 
 program

packages/next/src/build/next-config-ts/transpile-config.ts

@@ -116,7 +116,7 @@ export async function transpileConfig({
 }) {
   try {
     // envs are passed to the workers and preserve the flag
-    if (process.env.__NEXT_NODE_NATIVE_TS_LOADER_FAILED !== '1') {
+    if (process.env.__NEXT_NODE_NATIVE_TS_LOADER_ENABLED === 'true') {
       try {
         // Node.js v22.10.0+
         // Value is 'strip' or 'transform' based on how the feature is enabled.
@@ -139,7 +139,7 @@ export async function transpileConfig({
         }
 
         // Feature is not enabled, fallback to legacy resolution for current session.
-        process.env.__NEXT_NODE_NATIVE_TS_LOADER_FAILED = '1'
+        process.env.__NEXT_NODE_NATIVE_TS_LOADER_ENABLED = 'false'
       } catch (cause) {
         warnOnce(
           `Failed to import "${configFileName}" using Node.js native TypeScript resolution.` +
@@ -148,7 +148,7 @@ export async function transpileConfig({
           { cause }
         )
         // Once failed, fallback to legacy resolution for current session.
-        process.env.__NEXT_NODE_NATIVE_TS_LOADER_FAILED = '1'
+        process.env.__NEXT_NODE_NATIVE_TS_LOADER_ENABLED = 'false'
       }
     }
 

packages/next/src/cli/next-build.ts

@@ -25,6 +25,7 @@ export type NextBuildOptions = {
   experimentalTurbo?: boolean
   experimentalBuildMode: 'default' | 'compile' | 'generate' | 'generate-env'
   experimentalUploadTrace?: string
+  experimentalNextConfigStripTypes?: boolean
 }
 
 const nextBuild = (options: NextBuildOptions, directory?: string) => {

packages/next/src/cli/next-dev.ts

@@ -56,6 +56,7 @@ export type NextDevOptions = {
   experimentalHttpsCert?: string
   experimentalHttpsCa?: string
   experimentalUploadTrace?: string
+  experimentalNextConfigStripTypes?: boolean
 }
 
 type PortSource = 'cli' | 'default' | 'env'

packages/next/src/cli/next-start.ts

@@ -13,6 +13,7 @@ export type NextStartOptions = {
   port: number
   hostname?: string
   keepAliveTimeout?: number
+  experimentalNextConfigStripTypes?: boolean
 }
 
 /**