feat(next): next.config.ts

docs/02-app/01-building-your-application/07-configuring/01-typescript.mdx

@@ -31,6 +31,8 @@ Add TypeScript to your project by renaming a file to `.ts` / `.tsx`. Run `next d
 
 If you already had a `jsconfig.json` file, copy the `paths` compiler option from the old `jsconfig.json` into the new `tsconfig.json` file, and delete the old `jsconfig.json` file.
 
+We also recommend you to use `next.config.ts` over `next.config.js` for better type inference.
+
 <AppOnly>
 
 ## TypeScript Plugin
@@ -70,6 +72,22 @@ The TypeScript plugin can help with:
 
 It is highly recommended to be on at least `v4.5.2` of TypeScript to get syntax features such as [type modifiers on import names](https://devblogs.microsoft.com/typescript/announcing-typescript-4-5/#type-on-import-names) and [performance improvements](https://devblogs.microsoft.com/typescript/announcing-typescript-4-5/#real-path-sync-native).
 
+## Type checking with `next.config.ts`
+
+You can use TypeScript in your Next.js configuration by using `next.config.ts`. If you have a `next.config.js` or `next.config.mjs` file, you can rename it to `next.config.ts`, and will be able to use TypeScript without any change in the configuration.
+
+Although you can use `module.exports` syntax in `next.config.ts`, it is recommended to use the `export default` syntax for better type inference.
+
+```ts filename="next.config.ts"
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  /* config options here */
+}
+
+export default nextConfig
+```
+
 <AppOnly>
 
 ## Statically Typed Links
@@ -78,15 +96,16 @@ Next.js can statically type links to prevent typos and other errors when using `
 
 To opt-into this feature, `experimental.typedRoutes` need to be enabled and the project needs to be using TypeScript.
 
-```js filename="next.config.js"
-/** @type {import('next').NextConfig} */
-const nextConfig = {
+```js filename="next.config.ts"
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
   experimental: {
     typedRoutes: true,
   },
 }
 
-module.exports = nextConfig
+export default nextConfig
 ```
 
 Next.js will generate a link definition in `.next/types` that contains information about all existing routes in your application, which TypeScript can then use to provide feedback in your editor about invalid links.
@@ -251,23 +270,6 @@ You can learn more about this feature on the [Module Path aliases documentation]
 
 </PagesOnly>
 
-## Type checking next.config.js
-
-The `next.config.js` file must be a JavaScript file as it does not get parsed by Babel or TypeScript, however you can add some type checking in your IDE using JSDoc as below:
-
-```js
-// @ts-check
-
-/**
- * @type {import('next').NextConfig}
- **/
-const nextConfig = {
-  /* config options here */
-}
-
-module.exports = nextConfig
-```
-
 ## Incremental type checking
 
 Since `v10.2.1` Next.js supports [incremental type checking](https://www.typescriptlang.org/tsconfig#incremental) when enabled in your `tsconfig.json`, this can help speed up type checking in larger applications.
@@ -280,10 +282,10 @@ If you'd like Next.js to dangerously produce production code even when your appl
 
 If disabled, be sure you are running type checks as part of your build or deploy process, otherwise this can be very dangerous.
 
-Open `next.config.js` and enable the `ignoreBuildErrors` option in the `typescript` config:
+Open `next.config.ts` and enable the `ignoreBuildErrors` option in the `typescript` config:
 
-```js filename="next.config.js"
-module.exports = {
+```ts filename="next.config.ts"
+export default {
   typescript: {
     // !! WARN !!
     // Dangerously allow production builds to successfully complete even if
@@ -319,6 +321,7 @@ When you need to declare custom types, you might be tempted to modify `next-env.
 
 | Version   | Changes                                                                                                                              |
 | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `v14.2.0` | `next.config.ts` support added for TypeScript projects.                                                                              |
 | `v13.2.0` | Statically typed links are available in beta.                                                                                        |
 | `v12.0.0` | [SWC](/docs/architecture/nextjs-compiler) is now used by default to compile TypeScript and TSX for faster builds.                    |
 | `v10.2.1` | [Incremental type checking](https://www.typescriptlang.org/tsconfig#incremental) support added when enabled in your `tsconfig.json`. |

docs/02-app/02-api-reference/05-next-config-js/index.mdx

@@ -20,6 +20,22 @@ module.exports = nextConfig
 
 `next.config.js` is a regular Node.js module, not a JSON file. It gets used by the Next.js server and build phases, and it's not included in the browser build.
 
+## TypeScript
+
+If you are using TypeScript in your project, you can use [`next.config.ts`](https://nextjs.org/docs/app/building-your-application/configuring/typescript#type-checking-with-next-config-ts) to use TypeScript in your configuration:
+
+```ts filename="next.config.ts"
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  /* config options here */
+}
+
+export default nextConfig
+```
+
+## ECMAScript modules
+
 If you need [ECMAScript modules](https://nodejs.org/api/esm.html), you can use `next.config.mjs`:
 
 ```js filename="next.config.mjs"
@@ -35,7 +51,21 @@ const nextConfig = {
 export default nextConfig
 ```
 
-You can also use a function:
+Or `next.config.mts` for TypeScript:
+
+```ts filename="next.config.mts"
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  /* config options here */
+}
+
+export default nextConfig
+```
+
+## Configuration as function
+
+You can use the configuration as a function:
 
 ```js filename="next.config.mjs"
 // @ts-check
@@ -69,7 +99,7 @@ module.exports = async (phase, { defaultConfig }) => {
 
 `phase` is the current context in which the configuration is loaded. You can see the [available phases](https://github.com/vercel/next.js/blob/5e6b008b561caf2710ab7be63320a3d549474a5b/packages/next/shared/lib/constants.ts#L19-L23). Phases can be imported from `next/constants`:
 
-```js
+```js filename="next.config.js"
 // @ts-check
 
 const { PHASE_DEVELOPMENT_SERVER } = require('next/constants')
@@ -91,6 +121,6 @@ The commented lines are the place where you can put the configs allowed by `next
 
 However, none of the configs are required, and it's not necessary to understand what each config does. Instead, search for the features you need to enable or modify in this section and they will show you what to do.
 
-> Avoid using new JavaScript features not available in your target Node.js version. `next.config.js` will not be parsed by Webpack, Babel or TypeScript.
+> Avoid using new JavaScript features not available in your target Node.js version. `next.config.js` will not be parsed by Webpack, Babel or TypeScript. Instead, use `next.config.mjs` for ECMAScript modules or `next.config.ts` for TypeScript.
 
 This page documents all the available configuration options:

docs/02-app/02-api-reference/05-next-config-js/typescript.mdx

@@ -11,10 +11,10 @@ If you'd like Next.js to dangerously produce production code even when your appl
 
 If disabled, be sure you are running type checks as part of your build or deploy process, otherwise this can be very dangerous.
 
-Open `next.config.js` and enable the `ignoreBuildErrors` option in the `typescript` config:
+Open `next.config.ts` and enable the `ignoreBuildErrors` option in the `typescript` config:
 
-```js filename="next.config.js"
-module.exports = {
+```ts filename="next.config.ts"
+export default {
   typescript: {
     // !! WARN !!
     // Dangerously allow production builds to successfully complete even if

packages/create-next-app/templates/app-tw/ts/next.config.ts

@@ -0,0 +1,5 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {};
+
+export default nextConfig;

packages/create-next-app/templates/app/ts/next.config.ts

@@ -0,0 +1,5 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {};
+
+export default nextConfig;

packages/create-next-app/templates/default-tw/ts/next.config.ts

@@ -0,0 +1,5 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = { reactStrictMode: true };
+
+export default nextConfig;

packages/create-next-app/templates/default/ts/next.config.ts

@@ -0,0 +1,5 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = { reactStrictMode: true };
+
+export default nextConfig;

packages/next/src/build/swc/options.ts

@@ -17,7 +17,11 @@ const regeneratorRuntimePath = require.resolve(
 )
 
 function isTypeScriptFile(filename: string) {
-  return filename.endsWith('.ts') || filename.endsWith('.tsx')
+  return (
+    filename.endsWith('.ts') ||
+    filename.endsWith('.mts') ||
+    filename.endsWith('.tsx')
+  )
 }
 
 function isCommonJSFile(filename: string) {