feat(next): `next.config.ts` #57656

devjiwonchoi · 2023-10-28T05:56:22Z

Ported to #63051

What?

This PR initiated support of next.config.ts using SWC and webpack.

Add docs for next.config.ts.
Modify create-next-app for TS to create next.config.ts by default.

Why?

Next.js provides a TypeScript-first development experience for building your React application.

This PR can resolve the two main needs:

Import TS files to the config.
Conduct a type check directly by importing type not JSDoc.

As mentioned in #35969 (comment), it became possible to transpile the config fast enough to have less pain on DX.
The current method impacts the transpilation time less than a 0.1s increase in HMR.

x-ref: #5318 #35969 #44632 #50121 #50126

How?

Used webpack as mentioned in #50126 (review), only on cases where the config imports other modules.

Transpile-only with SWC if the config has no valid imports(types or unused), which is the case for most users.
If the imports are given, bundle with webpack to resolve imports with various conditions and extensions.
To import Native ESM packages in the CommonJS(default for Next.js) project, next.config.mts can handle it.
On the production server, use build cache if exists.

Restrictions

The compiled config will be stored in the .next directory, regardless of the distDir option in the config.
The __filename will return next.config.ts instead of the default behavior returning the absolute file path.

Expected & Edge Cases

Added tests for the cases below:

config as an async function
export { x as default }
import alias (tsconfig baseUrl and paths)
import from node_modules
use Node.js API (fs, path, etc.)
nested imports (config -> A -> B)
migration from next.config.js without change

Native ESM (package.json `type: module`)

importing .cts
importing .cjs
importing .js (ESM)

CJS

importing Native ESM packages (use next.config.mts)
importing .mts
importing .mjs
importing .js (CJS)

Transpilation Speed Profile (format: `second`)

Open Stats

Test Settings

next.config.ts

Transpile-only (no import)

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  env: {
    foo: 'foo',
  },
}

export default nextConfig

Bundle-webpack (has import)

import type { NextConfig } from 'next'
import { foo } from './foo'

const nextConfig: NextConfig = {
  env: {
    foo,
  },
}

export default nextConfig

`next dev`

Transpile-only (no import)

0.002s
0.002s
0.001s
0.002s
0.002s

Bundle-webpack (has import)

0.069s
0.073s
0.070s
0.069s
0.069s

`next build`

Transpile-only (no import)

3.237s
3.231s
3.379s
3.481s
3.654s

Bundle-webpack (has import)

3.374s
3.372s
3.332s
3.768s
3.424s

`next start`

Transpile-only (no import)

0.001s
0.001s
0.001s
0.001s
0.001s

Bundle-webpack (has import)

0.001s
0.001s
0.001s
0.001s
0.001s

Spec

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 23.1.0: Mon Oct  9 21:32:11 PDT 2023; root:xnu-10002.41.9~7/RELEASE_ARM64_T6030
  Available memory (MB): 18432
  Available CPU cores: 11
Binaries:
  Node: 18.17.1
  npm: 9.6.7
  Yarn: N/A
  pnpm: 8.15.1
Relevant Packages:
  next: 14.1.2-canary.2 // Latest available version is detected (14.1.2-canary.2).
  eslint-config-next: 14.1.2-canary.2
  react: 18.2.0
  react-dom: 18.2.0
  typescript: 5.2.2
Next.js Config:
  output: N/A

ijjk · 2023-10-28T05:56:45Z

Allow CI Workflow Run

approve CI run for commit: 1a61b97

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

vercel-spaces · 2023-10-28T06:28:31Z

Notifying the following users due to files changed in this PR based on this repo's notify modifiers:

@timneutkens, @ijjk, @shuding, @huozhi:

packages/next/src/server/config.ts

kdy1 · 2023-10-28T06:47:05Z

swc-loader does not have caching logic because transforming every time with SWC was faster than caching due to comparison cost and extra FS operations. Did you profile it?

devjiwonchoi · 2023-10-28T06:51:44Z

I'll remove the caching part. Thank you!

ref: #57656 (comment) Co-authored-by: Donny/강동윤 <[email protected]>

AhmedBaset · 2023-10-28T18:23:42Z

I opened a PR devjiwonchoi#1 to make create-next-app create next.config.ts by default when using TypeScript

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

Co-authored-by: rodrigo <[email protected]>

devjiwonchoi · 2024-03-03T14:01:00Z

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

@@ -319,6 +319,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.                                                                              |


Temporarily set version as v14.2.0

This reverts commit 8e4c38e.

devjiwonchoi

@ijjk These were the final attempts I tried before moving back to webpack.

devjiwonchoi · 2024-03-05T03:42:01Z

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

-      const swc = transformSync(code, swcOptions)
-      return originalCompile.call(this, swc.code, filename)
+  if (isESM) {
+    // TODO: Implement importing ESM


I tried to modify require.extensions['.js'] behavior as:

if (isESM) { delete (require as any).extensions['.js'] transformableExtensions.push('.js') }

Received error:

> Build error occurred Error [ERR_REQUIRE_ESM]: require() of ES Module /tmp/node_modules/esm/foo.js from /tmp/next.config.cjs not supported. Instead change the require of foo.js in /tmp/next.config.cjs to a dynamic import() which is available in all CommonJS modules. at require.extensions.<computed> [as .js]

devjiwonchoi · 2024-03-05T03:43:14Z

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

@@ -101,7 +106,6 @@ export async function transpileConfig({
    throw error
  } finally {
    await unlink(tempConfigPath).catch(() => {})


Revert the .js hook.

transformableExtensions.forEach((ext) => delete require.extensions[ext]) require.extensions['.js'] = originalJsHandler await unlink(tempConfigPath).catch(() => {})

AhmedBaset · 2024-03-08T15:16:10Z

Why this was closed?

devjiwonchoi · 2024-03-08T15:26:19Z

I accidentally deleted the head, finding a way to restore it 😅

joulev · 2024-03-08T16:33:30Z

Phew, I was really looking forward to this feature, and it would be a shame if this was closed intentionally. Please keep up the good work, a large number of users will benefit from this feature!

devjiwonchoi · 2024-03-09T01:09:42Z

@joulev Thank you for your support! I'll do my best to ship it as efficiently as possible. 😄

devjiwonchoi added 5 commits October 27, 2023 12:15

allow next.config.ts on load

7c24a69

test: add test for next.config.ts

21b18e0

add compile config

407658d

chore: compile as mjs

3075e2a

test: add test case for production

bd61aec

ijjk added area: tests type: next labels Oct 28, 2023

devjiwonchoi added 2 commits October 28, 2023 15:20

chore: add cache original config and skip compile if identical

4ba992b

Merge branch 'canary' into next-config-ts-esm

5fcfd50

devjiwonchoi marked this pull request as ready for review October 28, 2023 06:28

devjiwonchoi requested review from timneutkens, ijjk, shuding, huozhi, ztanner, feedthejim, a team and wyattjoh as code owners October 28, 2023 06:28

add next.config.ts to error message

834bdba

remove caching snapshot of config

7c25030

ref: #57656 (comment) Co-authored-by: Donny/강동윤 <[email protected]>

devjiwonchoi changed the title ~~feat(next-config): Support next config as TypeScript file~~ feat(next): Support next.config.ts Oct 28, 2023

falsepopsky reviewed Oct 28, 2023

View reviewed changes

packages/next/src/build/compile-config.ts Outdated Show resolved Hide resolved

devjiwonchoi added 3 commits October 29, 2023 12:35

fix: modify target version to esnext

7a0518c

Co-authored-by: rodrigo <[email protected]>

refac: convert to async job, error handle

5a394a9

test: modify test to look for rendered element

cd2c8d8

devjiwonchoi requested a review from a team as a code owner March 3, 2024 13:57

devjiwonchoi requested review from jh3y and molebox and removed request for a team, SukkaW and falsepopsky March 3, 2024 13:57

ijjk added the area: documentation label Mar 3, 2024

devjiwonchoi commented Mar 3, 2024

View reviewed changes

devjiwonchoi added 11 commits March 3, 2024 23:54

Merge branch 'canary' into next-config-ts-esm

8800145

test: add dev

32fd66e

refactor: use build cache on production server if exists

34af164

refactor: remove unintended change

9890443

refactor: try transpile-only first before any other operation

baaad07

test: add export default

b7f50ab

refactor: join cwd with distDir to dedupe join operation

c7765c8

refactor: let loadConfig handle added default export of SWC transform

c1e796f

test: add cjs syntax for direct migration from .js

8bd8863

docs: add we recommend next.config.ts if you are migrating to TS

79b643d

fix: do not pass an absolute path to distDir

8e4c38e

devjiwonchoi requested a review from samcx as a code owner March 4, 2024 01:31

Revert "fix: do not pass an absolute path to distDir"

1a61b97

This reverts commit 8e4c38e.

devjiwonchoi commented Mar 5, 2024

View reviewed changes

devjiwonchoi closed this by deleting the head repository Mar 8, 2024

devjiwonchoi mentioned this pull request Mar 8, 2024

feat(next): next.config.ts #63051

Merged

20 tasks

github-actions bot added the locked label Mar 23, 2024

github-actions bot locked as resolved and limited conversation to collaborators Mar 23, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(next): `next.config.ts` #57656

feat(next): `next.config.ts` #57656

devjiwonchoi commented Oct 28, 2023 •

edited

Loading

ijjk commented Oct 28, 2023 •

edited

Loading

vercel-spaces bot commented Oct 28, 2023 •

edited

Loading

kdy1 commented Oct 28, 2023

devjiwonchoi commented Oct 28, 2023

AhmedBaset commented Oct 28, 2023

devjiwonchoi Mar 3, 2024

devjiwonchoi left a comment

devjiwonchoi Mar 5, 2024

devjiwonchoi Mar 5, 2024

devjiwonchoi Mar 5, 2024

AhmedBaset commented Mar 8, 2024

devjiwonchoi commented Mar 8, 2024

joulev commented Mar 8, 2024

devjiwonchoi commented Mar 9, 2024

feat(next): next.config.ts #57656

feat(next): next.config.ts #57656

Conversation

devjiwonchoi commented Oct 28, 2023 • edited Loading

Ported to #63051

What?

Why?

How?

Restrictions

Expected & Edge Cases

Native ESM (package.json type: module)

CJS

Transpilation Speed Profile (format: second)

Test Settings

Transpile-only (no import)

Bundle-webpack (has import)

next dev

Transpile-only (no import)

Bundle-webpack (has import)

next build

Transpile-only (no import)

Bundle-webpack (has import)

next start

Transpile-only (no import)

Bundle-webpack (has import)

Spec

ijjk commented Oct 28, 2023 • edited Loading

vercel-spaces bot commented Oct 28, 2023 • edited Loading

kdy1 commented Oct 28, 2023

devjiwonchoi commented Oct 28, 2023

AhmedBaset commented Oct 28, 2023

devjiwonchoi Mar 3, 2024

Choose a reason for hiding this comment

devjiwonchoi left a comment

Choose a reason for hiding this comment

devjiwonchoi Mar 5, 2024

Choose a reason for hiding this comment

devjiwonchoi Mar 5, 2024

Choose a reason for hiding this comment

devjiwonchoi Mar 5, 2024

Choose a reason for hiding this comment

AhmedBaset commented Mar 8, 2024

devjiwonchoi commented Mar 8, 2024

joulev commented Mar 8, 2024

devjiwonchoi commented Mar 9, 2024

feat(next): `next.config.ts` #57656

feat(next): `next.config.ts` #57656

devjiwonchoi commented Oct 28, 2023 •

edited

Loading

Native ESM (package.json `type: module`)

Transpilation Speed Profile (format: `second`)

`next dev`

`next build`

`next start`

ijjk commented Oct 28, 2023 •

edited

Loading

vercel-spaces bot commented Oct 28, 2023 •

edited

Loading