Skip to content

Commit cbf0cef

Browse files
timneutkenstimneutkens
authored
Enable TypeScript CLI by default (#96497)
## Summary Enable the project-local TypeScript CLI checker by default during `next build`, while preserving `experimental.useTypeScriptCli: false` as an opt-out to the TypeScript compiler API. Update the TypeScript 7 guidance, diagnostics, tests, and documentation to match the new default. ## Verification - `pnpm exec jest --runTestsByPath test/unit/isolated/config.test.ts` - Pre-commit lint-staged checks passed (Prettier and ESLint) - Not run: `pnpm test-start-turbo test/production/app-dir/typescript-cli/typescript-cli.test.ts` (isolated fixture dependency installation was blocked by unavailable npm registry access) - Not run: `pnpm --filter=next types` (repository has pre-existing unrelated TypeScript errors) <!-- NEXT_JS_LLM -->
1 parent dcdacfd commit cbf0cef

24 files changed

Lines changed: 134 additions & 54 deletions

File tree

‎docs/01-app/03-api-reference/05-config/01-next-config-js/useTypeScriptCli.mdx‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Run the project-local TypeScript CLI for type checking during produ
44
version: experimental
55
---
66

7-
The `experimental.useTypeScriptCli` option makes `next build` run the project-local `tsc` command instead of loading the TypeScript JavaScript compiler API. You can use this option with TypeScript 6, and it enables [TypeScript 7](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/) support while its JavaScript API is unavailable.
7+
By default, `next build` runs the project-local `tsc` command instead of loading the TypeScript JavaScript compiler API. This supports TypeScript 6 and enables [TypeScript 7](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/) while its JavaScript API is unavailable.
88

99
Install TypeScript 7 in your project:
1010

@@ -24,14 +24,14 @@ yarn add -D typescript@^7
2424
bun add -D typescript@^7
2525
```
2626

27-
Then, explicitly enable the CLI checker:
27+
The CLI checker is enabled by default. To use the TypeScript JavaScript compiler API instead, set `experimental.useTypeScriptCli` to `false`:
2828

2929
```ts filename="next.config.ts" switcher
3030
import type { NextConfig } from 'next'
3131

3232
const nextConfig: NextConfig = {
3333
experimental: {
34-
useTypeScriptCli: true,
34+
useTypeScriptCli: false,
3535
},
3636
}
3737

@@ -42,14 +42,14 @@ export default nextConfig
4242
/** @type {import('next').NextConfig} */
4343
const nextConfig = {
4444
experimental: {
45-
useTypeScriptCli: true,
45+
useTypeScriptCli: false,
4646
},
4747
}
4848

4949
module.exports = nextConfig
5050
```
5151

52-
Next.js does not select the CLI checker automatically. If TypeScript 7 is installed without this option, `next build` exits with instructions to enable it or install a TypeScript version supported by the default checker.
52+
If you opt out while using TypeScript 7, `next build` exits because the TypeScript JavaScript compiler API is unavailable.
5353

5454
## Behavior
5555

‎docs/01-app/03-api-reference/05-config/02-typescript.mdx‎

Lines changed: 3 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ To add TypeScript to an existing project, rename a file to `.ts` / `.tsx`. Run `
1313
1414
## Using TypeScript 7
1515

16-
[TypeScript 7](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/) does not currently provide the JavaScript compiler API that Next.js uses for type checking by default. To use TypeScript 7 during `next build`, install it in your project:
16+
[TypeScript 7](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/) does not currently provide the JavaScript compiler API. To use TypeScript 7 during `next build`, install it in your project:
1717

1818
```bash package="pnpm"
1919
pnpm add -D typescript@^7
@@ -31,32 +31,7 @@ yarn add -D typescript@^7
3131
bun add -D typescript@^7
3232
```
3333

34-
Then, opt in to running the project-local `tsc` CLI instead of the JavaScript API with [`experimental.useTypeScriptCli`](/docs/app/api-reference/config/next-config-js/useTypeScriptCli):
35-
36-
```ts filename="next.config.ts" switcher
37-
import type { NextConfig } from 'next'
38-
39-
const nextConfig: NextConfig = {
40-
experimental: {
41-
useTypeScriptCli: true,
42-
},
43-
}
44-
45-
export default nextConfig
46-
```
47-
48-
```js filename="next.config.js" switcher
49-
/** @type {import('next').NextConfig} */
50-
const nextConfig = {
51-
experimental: {
52-
useTypeScriptCli: true,
53-
},
54-
}
55-
56-
module.exports = nextConfig
57-
```
58-
59-
Next.js does not enable this option automatically. If you install TypeScript 7 without enabling `experimental.useTypeScriptCli`, `next build` exits with instructions to enable the option or install a TypeScript version supported by the default checker.
34+
Next.js uses the project-local `tsc` CLI by default, so no additional configuration is required. To use the JavaScript compiler API instead, set [`experimental.useTypeScriptCli`](/docs/app/api-reference/config/next-config-js/useTypeScriptCli) to `false`.
6035

6136
> **Good to know**:
6237
>
@@ -85,7 +60,7 @@ You can enable the plugin in VS Code by:
8560
height="637"
8661
/>
8762

88-
Now, when editing files, the custom plugin will be enabled. By default, the custom type checker is used when running `next build`. When [`experimental.useTypeScriptCli`](#using-typescript-7) is enabled, the project-local `tsc` CLI is used instead.
63+
Now, when editing files, the custom plugin will be enabled. By default, the project-local `tsc` CLI is used when running `next build`. Set [`experimental.useTypeScriptCli`](#using-typescript-7) to `false` to use the custom type checker instead.
8964

9065
The TypeScript plugin can help with:
9166

‎packages/next/errors.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1463,5 +1463,7 @@
14631463
"1462": "Unexpected chunk emitted in Before stage",
14641464
"1463": "\\`experimental.turbopackGenerateComponentChunks\\` has been moved to \\`experimental.turbopackChunking.generateComponentChunks\\`. Please update your next.config.js file accordingly.",
14651465
"1464": "\\`experimental.turbopackChunkingHeuristics\\` has been renamed to \\`experimental.turbopackChunking\\`. Please update your next.config.js file accordingly.",
1466-
"1465": "\\`experimental.useCache\\` cannot be disabled when \\`cacheComponents\\` is enabled, because Cache Components relies on the \\`\"use cache\"\\` directive. Please remove it from %s."
1466+
"1465": "\\`experimental.useCache\\` cannot be disabled when \\`cacheComponents\\` is enabled, because Cache Components relies on the \\`\"use cache\"\\` directive. Please remove it from %s.",
1467+
"1466": "TypeScript %s does not provide the compiler API required by Next.js. Set %s to true in your Next.js config to use the TypeScript CLI, or install TypeScript 6 instead.",
1468+
"1467": "TypeScript %s does not provide the compiler API required by Next.js. Set %s back to true in your Next.js config to use the TypeScript CLI, or install TypeScript 6 instead."
14671469
}

‎packages/next/src/lib/typescript/runTypeScriptCli.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ export function hasNativeTypeScriptPreview(baseDir: string): boolean {
7373
export function getTypeScriptApiMissingError(version: string): Error {
7474
return new Error(
7575
`TypeScript ${version} does not provide the compiler API required by Next.js. ` +
76-
`Enable ${bold('experimental.useTypeScriptCli')} in your Next.js config to use the TypeScript CLI, ` +
76+
`Set ${bold('experimental.useTypeScriptCli')} back to true in your Next.js config to use the TypeScript CLI, ` +
7777
`or install TypeScript 6 instead.`
7878
)
7979
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2223,7 +2223,7 @@ export const defaultConfig = Object.freeze({
22232223
webpackMemoryOptimizations: false,
22242224
optimizeServerReact: true,
22252225
strictRouteTypes: false,
2226-
useTypeScriptCli: false,
2226+
useTypeScriptCli: true,
22272227
removeUncaughtErrorAndRejectionListeners: false,
22282228
validateRSCRequestHeaders: true,
22292229
staleTimes: {

‎test/development/basic/legacy-decorators.test.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@ import { check } from 'next-test-utils'
55
describe('Legacy decorators SWC option', () => {
66
describe('with extended tsconfig', () => {
77
const { next } = nextTestSetup({
8+
nextConfig: {
9+
experimental: { useTypeScriptCli: false },
10+
},
811
files: {
912
'tsconfig.json': new FileRef(
1013
join(__dirname, 'legacy-decorators/tsconfig-extended.json')

‎test/development/stale-dev-types/stale-dev-types.test.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@ import { retry } from 'next-test-utils'
44
describe('stale-dev-types', () => {
55
const { next } = nextTestSetup({
66
files: __dirname,
7+
nextConfig: {
8+
experimental: {
9+
useTypeScriptCli: false,
10+
},
11+
},
712
})
813

914
it('should not fail build when .next/dev has stale types from deleted routes', async () => {

‎test/development/typescript-native-preview/index.test.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,11 @@ import { retry } from 'next-test-utils'
33

44
describe('typescript-native-preview', () => {
55
const { next } = nextTestSetup({
6+
nextConfig: {
7+
experimental: {
8+
useTypeScriptCli: false,
9+
},
10+
},
611
files: {
712
'app/layout.tsx': `
813
import { ReactNode } from 'react'

‎test/e2e/app-dir/typed-routes-validator/next.config.js‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
/**
22
* @type {import('next').NextConfig}
33
*/
4-
const nextConfig = {}
4+
const nextConfig = {
5+
experimental: {
6+
useTypeScriptCli: false,
7+
},
8+
}
59

610
module.exports = nextConfig

‎test/e2e/app-dir/typed-routes/next.config.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ setInterval(() => {}, 250)
66
*/
77
const nextConfig = {
88
typedRoutes: true,
9+
experimental: {
10+
useTypeScriptCli: false,
11+
},
912
async redirects() {
1013
return [
1114
{

0 commit comments

Comments
 (0)