chore: add experimental warning

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

@@ -1,5 +1,6 @@
 import type { CompilerOptions } from 'typescript'
 import type { Options as SWCOptions } from '@swc/core'
+import type { NextConfig } from '../../types'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { deregisterHook, registerHook, requireFromString } from './require-hook'
@@ -48,7 +49,7 @@ export async function transpileConfig({
 }: {
   nextConfigPath: string
   cwd: string
-}) {
+}): Promise<NextConfig> {
   let hasRequire = false
   try {
     const { compilerOptions } = await lazilyGetTSConfig(cwd)

packages/next/src/server/config-schema.ts

@@ -248,6 +248,7 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
     excludeDefaultMomentLocales: z.boolean().optional(),
     experimental: z
       .strictObject({
+        nextConfigTs: z.boolean().optional(),
         after: z.boolean().optional(),
         appDocumentPreloading: z.boolean().optional(),
         preloadEntriesOnStart: z.boolean().optional(),

packages/next/src/server/config-shared.ts

@@ -200,6 +200,10 @@ export interface ReactCompilerOptions {
 }
 
 export interface ExperimentalConfig {
+  /**
+   * Enable next.config.ts, defaults to true
+   */
+  nextConfigTs?: boolean
   flyingShuttle?: boolean
   prerenderEarlyExit?: boolean
   linkNoTouchStart?: boolean
@@ -991,6 +995,7 @@ export const defaultConfig: NextConfig = {
     reactCompiler: undefined,
     after: false,
     staticGenerationRetryCount: undefined,
+    nextConfigTs: true,
   },
   bundlePagesRouterDependencies: false,
 }

packages/next/src/server/config.ts

@@ -969,9 +969,6 @@ export default async function loadConfig(
           nextConfigPath: path,
           cwd: dir,
         })
-        curLog.warn(
-          `Configuration with ${configFileName} is currently an experimental feature, use with caution.`
-        )
       } else {
         userConfigModule = await import(pathToFileURL(path).href)
       }
@@ -1034,6 +1031,16 @@ export default async function loadConfig(
       }
     }
 
+    if (
+      configFileName === 'next.config.ts' &&
+      !userConfig.experimental?.nextConfigTs
+    ) {
+      // warn when using next.config.ts but experimental.nextConfigTs is set to false
+      curLog.warn(
+        `Configuration with ${configFileName} is currently an experimental feature, use with caution.`
+      )
+    }
+
     if (userConfig.target && userConfig.target !== 'server') {
       throw new Error(
         `The "target" property is no longer supported in ${configFileName}.\n` +

test/development/app-dir/next-config-ts/experimental-warning.test.ts

@@ -0,0 +1,15 @@
+import { nextTestSetup } from 'e2e-utils'
+import { check } from 'next-test-utils'
+
+describe('next-config-ts - experimental-warning', () => {
+  const { next } = nextTestSetup({
+    files: __dirname,
+  })
+
+  it('should warn if experimental.nextConfigTs is set to false', async () => {
+    await check(
+      async () => next.cliOutput,
+      /is currently an experimental feature, use with caution/i
+    )
+  })
+})

test/development/app-dir/hmr-next-config-ts/index.test.ts → test/development/app-dir/next-config-ts/hmr.test.ts

@@ -1,10 +1,11 @@
 import { nextTestSetup } from 'e2e-utils'
 import { check } from 'next-test-utils'
 
-describe('hmr-next-config-ts', () => {
+describe('next-config-ts - hmr', () => {
   const { next } = nextTestSetup({
     files: __dirname,
   })
+
   it('should output config file change', async () => {
     await check(async () => next.cliOutput, /ready/i)
 

test/development/app-dir/hmr-next-config-ts/next.config.ts → test/development/app-dir/next-config-ts/next.config.ts

@@ -1,6 +1,9 @@
 import type { NextConfig } from 'next'
 
 const nextConfig = {
+  experimental: {
+    nextConfigTs: false,
+  },
   // target
 } satisfies NextConfig