Skip to content
Projects
Groups
Snippets
Help
Loading...
Sign in
Toggle navigation
N
next.js
Project
Project
Details
Activity
Cycle Analytics
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Charts
Issues
0
Issues
0
List
Board
Labels
Milestones
Merge Requests
0
Merge Requests
0
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Charts
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Charts
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
Alex
next.js
Commits
42493fb3
Unverified
Commit
42493fb3
authored
Jan 05, 2026
by
Jiachi Liu
Committed by
GitHub
Jan 05, 2026
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
dx: avoid next-env.d.ts change in dev (#88103)
parent
c5b19eb7
Show whitespace changes
Inline
Side-by-side
Showing
10 changed files
with
85 additions
and
5 deletions
+85
-5
type-check.ts
packages/next/src/build/type-check.ts
+3
-0
next-test.ts
packages/next/src/cli/next-test.ts
+1
-0
next-typegen.ts
packages/next/src/cli/next-typegen.ts
+1
-0
writeAppTypeDeclarations.ts
packages/next/src/lib/typescript/writeAppTypeDeclarations.ts
+8
-3
verify-typescript-setup.ts
packages/next/src/lib/verify-typescript-setup.ts
+4
-0
route-types-utils.ts
...ges/next/src/server/lib/router-utils/route-types-utils.ts
+25
-0
setup-dev-bundler.ts
...ges/next/src/server/lib/router-utils/setup-dev-bundler.ts
+13
-0
isolated-dev-build.test.ts
...ent/app-dir/isolated-dev-build/isolated-dev-build.test.ts
+28
-0
next-env.d.ts
test/integration/custom-server-types/next-env.d.ts
+1
-1
next-env.d.ts
...ntegration/typescript-app-type-declarations/next-env.d.ts
+1
-1
No files found.
packages/next/src/build/type-check.ts
View file @
42493fb3
...
@@ -20,6 +20,7 @@ import { hrtimeDurationToString } from './duration-to-string'
...
@@ -20,6 +20,7 @@ import { hrtimeDurationToString } from './duration-to-string'
function
verifyTypeScriptSetup
(
function
verifyTypeScriptSetup
(
dir
:
string
,
dir
:
string
,
distDir
:
string
,
distDir
:
string
,
distDirRoot
:
string
|
undefined
,
typeCheckPreflight
:
boolean
,
typeCheckPreflight
:
boolean
,
tsconfigPath
:
string
|
undefined
,
tsconfigPath
:
string
|
undefined
,
disableStaticImages
:
boolean
,
disableStaticImages
:
boolean
,
...
@@ -50,6 +51,7 @@ function verifyTypeScriptSetup(
...
@@ -50,6 +51,7 @@ function verifyTypeScriptSetup(
.
verifyTypeScriptSetup
({
.
verifyTypeScriptSetup
({
dir
,
dir
,
distDir
,
distDir
,
distDirRoot
,
typeCheckPreflight
,
typeCheckPreflight
,
tsconfigPath
,
tsconfigPath
,
disableStaticImages
,
disableStaticImages
,
...
@@ -117,6 +119,7 @@ export async function startTypeChecking({
...
@@ -117,6 +119,7 @@ export async function startTypeChecking({
verifyTypeScriptSetup
(
verifyTypeScriptSetup
(
dir
,
dir
,
config
.
distDir
,
config
.
distDir
,
config
.
distDirRoot
,
!
ignoreTypeScriptErrors
,
!
ignoreTypeScriptErrors
,
config
.
typescript
.
tsconfigPath
,
config
.
typescript
.
tsconfigPath
,
config
.
images
.
disableStaticImages
,
config
.
images
.
disableStaticImages
,
...
...
packages/next/src/cli/next-test.ts
View file @
42493fb3
...
@@ -140,6 +140,7 @@ async function runPlaywright(
...
@@ -140,6 +140,7 @@ async function runPlaywright(
const
{
version
:
typeScriptVersion
}
=
await
verifyTypeScriptSetup
({
const
{
version
:
typeScriptVersion
}
=
await
verifyTypeScriptSetup
({
dir
:
baseDir
,
dir
:
baseDir
,
distDir
:
nextConfig
.
distDir
,
distDir
:
nextConfig
.
distDir
,
distDirRoot
:
nextConfig
.
distDirRoot
,
typeCheckPreflight
:
false
,
typeCheckPreflight
:
false
,
tsconfigPath
:
nextConfig
.
typescript
.
tsconfigPath
,
tsconfigPath
:
nextConfig
.
typescript
.
tsconfigPath
,
disableStaticImages
:
nextConfig
.
images
.
disableStaticImages
,
disableStaticImages
:
nextConfig
.
images
.
disableStaticImages
,
...
...
packages/next/src/cli/next-typegen.ts
View file @
42493fb3
...
@@ -57,6 +57,7 @@ const nextTypegen = async (
...
@@ -57,6 +57,7 @@ const nextTypegen = async (
await
verifyTypeScriptSetup
({
await
verifyTypeScriptSetup
({
dir
:
baseDir
,
dir
:
baseDir
,
distDir
:
nextConfig
.
distDir
,
distDir
:
nextConfig
.
distDir
,
distDirRoot
:
nextConfig
.
distDirRoot
,
typeCheckPreflight
:
false
,
typeCheckPreflight
:
false
,
tsconfigPath
:
nextConfig
.
typescript
.
tsconfigPath
,
tsconfigPath
:
nextConfig
.
typescript
.
tsconfigPath
,
disableStaticImages
:
nextConfig
.
images
.
disableStaticImages
,
disableStaticImages
:
nextConfig
.
images
.
disableStaticImages
,
...
...
packages/next/src/lib/typescript/writeAppTypeDeclarations.ts
View file @
42493fb3
...
@@ -5,12 +5,15 @@ import { promises as fs } from 'fs'
...
@@ -5,12 +5,15 @@ import { promises as fs } from 'fs'
export
async
function
writeAppTypeDeclarations
({
export
async
function
writeAppTypeDeclarations
({
baseDir
,
baseDir
,
distDir
,
distDir
,
distDirRoot
,
imageImportsEnabled
,
imageImportsEnabled
,
hasPagesDir
,
hasPagesDir
,
hasAppDir
,
hasAppDir
,
}:
{
}:
{
baseDir
:
string
baseDir
:
string
distDir
:
string
distDir
:
string
/** The original distDir before any modifications (e.g., for isolatedDevBuild). Used for stable type imports. */
distDirRoot
?:
string
imageImportsEnabled
:
boolean
imageImportsEnabled
:
boolean
hasPagesDir
:
boolean
hasPagesDir
:
boolean
hasAppDir
:
boolean
hasAppDir
:
boolean
...
@@ -57,10 +60,12 @@ export async function writeAppTypeDeclarations({
...
@@ -57,10 +60,12 @@ export async function writeAppTypeDeclarations({
)
)
}
}
const
routeTypesPath
=
path
.
posix
.
join
(
// Use distDirRoot for stable path that doesn't change between dev/build modes
distDir
.
replaceAll
(
path
.
win32
.
sep
,
path
.
posix
.
sep
),
const
stableDistDir
=
(
distDirRoot
??
distDir
).
replaceAll
(
'types/routes.d.ts'
path
.
win32
.
sep
,
path
.
posix
.
sep
)
)
const
routeTypesPath
=
path
.
posix
.
join
(
stableDistDir
,
'types/routes.d.ts'
)
// Use ESM import instead of triple-slash reference for better ESLint compatibility
// Use ESM import instead of triple-slash reference for better ESLint compatibility
directives
.
push
(
`import "./
${
routeTypesPath
}
";`
)
directives
.
push
(
`import "./
${
routeTypesPath
}
";`
)
...
...
packages/next/src/lib/verify-typescript-setup.ts
View file @
42493fb3
...
@@ -36,6 +36,7 @@ const requiredPackages = [
...
@@ -36,6 +36,7 @@ const requiredPackages = [
export
async
function
verifyTypeScriptSetup
({
export
async
function
verifyTypeScriptSetup
({
dir
,
dir
,
distDir
,
distDir
,
distDirRoot
,
cacheDir
,
cacheDir
,
tsconfigPath
,
tsconfigPath
,
typeCheckPreflight
,
typeCheckPreflight
,
...
@@ -49,6 +50,8 @@ export async function verifyTypeScriptSetup({
...
@@ -49,6 +50,8 @@ export async function verifyTypeScriptSetup({
}:
{
}:
{
dir
:
string
dir
:
string
distDir
:
string
distDir
:
string
/** The original distDir before any modifications (e.g., for isolatedDevBuild). */
distDirRoot
?:
string
cacheDir
?:
string
cacheDir
?:
string
tsconfigPath
:
string
|
undefined
tsconfigPath
:
string
|
undefined
typeCheckPreflight
:
boolean
typeCheckPreflight
:
boolean
...
@@ -143,6 +146,7 @@ export async function verifyTypeScriptSetup({
...
@@ -143,6 +146,7 @@ export async function verifyTypeScriptSetup({
await
writeAppTypeDeclarations
({
await
writeAppTypeDeclarations
({
baseDir
:
dir
,
baseDir
:
dir
,
distDir
,
distDir
,
distDirRoot
,
imageImportsEnabled
:
!
disableStaticImages
,
imageImportsEnabled
:
!
disableStaticImages
,
hasPagesDir
,
hasPagesDir
,
hasAppDir
,
hasAppDir
,
...
...
packages/next/src/server/lib/router-utils/route-types-utils.ts
View file @
42493fb3
...
@@ -395,3 +395,28 @@ export async function writeValidatorFile(
...
@@ -395,3 +395,28 @@ export async function writeValidatorFile(
:
generateValidatorFile
(
manifest
)
:
generateValidatorFile
(
manifest
)
)
)
}
}
/**
* Writes a proxy routes.d.ts file at the stable path that re-exports from
* the actual dev types location. This allows next-env.d.ts to always reference
* the same stable path regardless of dev/build mode.
*
* @param stableTypesDir - The stable types directory (e.g., .next/types)
* @param devTypesRelativePath - Relative path from stable dir to dev types (e.g., ../dev/types/routes.d.ts)
*/
export
async
function
writeRouteTypesProxy
(
stableTypesDir
:
string
,
devTypesRelativePath
:
string
)
{
if
(
!
fs
.
existsSync
(
stableTypesDir
))
{
await
fs
.
promises
.
mkdir
(
stableTypesDir
,
{
recursive
:
true
})
}
const
proxyFilePath
=
path
.
join
(
stableTypesDir
,
'routes.d.ts'
)
const
proxyContent
=
`// This file re-exports route types from the dev types location.
// This provides a stable import path for next-env.d.ts across dev/build modes.
export * from '
${
devTypesRelativePath
}
';
`
await
fs
.
promises
.
writeFile
(
proxyFilePath
,
proxyContent
)
}
packages/next/src/server/lib/router-utils/setup-dev-bundler.ts
View file @
42493fb3
...
@@ -85,6 +85,7 @@ import {
...
@@ -85,6 +85,7 @@ import {
createRouteTypesManifest
,
createRouteTypesManifest
,
writeRouteTypesManifest
,
writeRouteTypesManifest
,
writeValidatorFile
,
writeValidatorFile
,
writeRouteTypesProxy
,
}
from
'./route-types-utils'
}
from
'./route-types-utils'
import
{
writeCacheLifeTypes
}
from
'./cache-life-type-utils'
import
{
writeCacheLifeTypes
}
from
'./cache-life-type-utils'
import
{
isParallelRouteSegment
}
from
'../../../shared/lib/segment'
import
{
isParallelRouteSegment
}
from
'../../../shared/lib/segment'
...
@@ -143,6 +144,7 @@ async function verifyTypeScript(opts: SetupOpts) {
...
@@ -143,6 +144,7 @@ async function verifyTypeScript(opts: SetupOpts) {
const
verifyResult
=
await
verifyTypeScriptSetup
({
const
verifyResult
=
await
verifyTypeScriptSetup
({
dir
:
opts
.
dir
,
dir
:
opts
.
dir
,
distDir
:
opts
.
nextConfig
.
distDir
,
distDir
:
opts
.
nextConfig
.
distDir
,
distDirRoot
:
opts
.
nextConfig
.
distDirRoot
,
typeCheckPreflight
:
false
,
typeCheckPreflight
:
false
,
tsconfigPath
:
opts
.
nextConfig
.
typescript
.
tsconfigPath
,
tsconfigPath
:
opts
.
nextConfig
.
typescript
.
tsconfigPath
,
disableStaticImages
:
opts
.
nextConfig
.
images
.
disableStaticImages
,
disableStaticImages
:
opts
.
nextConfig
.
images
.
disableStaticImages
,
...
@@ -266,6 +268,17 @@ async function startWatcher(
...
@@ -266,6 +268,17 @@ async function startWatcher(
opts
.
nextConfig
opts
.
nextConfig
)
)
// When isolatedDevBuild is enabled, write a proxy file at the stable path
// that re-exports from the dev types location
if
(
opts
.
nextConfig
.
experimental
.
isolatedDevBuild
)
{
const
stableTypesDir
=
path
.
join
(
opts
.
dir
,
opts
.
nextConfig
.
distDirRoot
,
'types'
)
await
writeRouteTypesProxy
(
stableTypesDir
,
'../dev/types/routes.d.ts'
)
}
const
routesManifestPath
=
path
.
join
(
distDir
,
ROUTES_MANIFEST
)
const
routesManifestPath
=
path
.
join
(
distDir
,
ROUTES_MANIFEST
)
const
routesManifest
:
DevRoutesManifest
=
{
const
routesManifest
:
DevRoutesManifest
=
{
version
:
3
,
version
:
3
,
...
...
test/development/app-dir/isolated-dev-build/isolated-dev-build.test.ts
View file @
42493fb3
...
@@ -23,4 +23,32 @@ describe('isolated-dev-build', () => {
...
@@ -23,4 +23,32 @@ describe('isolated-dev-build', () => {
expect
(
await
browser
.
elementByCss
(
'p'
).
text
()).
toBe
(
'hello updated world'
)
expect
(
await
browser
.
elementByCss
(
'p'
).
text
()).
toBe
(
'hello updated world'
)
})
})
})
})
it
(
'should use stable path in next-env.d.ts that does not change between dev/build'
,
async
()
=>
{
const
nextEnvContent
=
await
next
.
readFile
(
'next-env.d.ts'
)
// Snapshot ensures next-env.d.ts content stays stable
expect
(
nextEnvContent
).
toMatchInlineSnapshot
(
`
"/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/types/routes.d.ts";
// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
"
`
)
})
it
(
'should create proxy routes.d.ts at stable path that re-exports from dev types'
,
async
()
=>
{
// The proxy file should re-export from the dev types location
const
proxyContent
=
await
next
.
readFile
(
'.next/types/routes.d.ts'
)
expect
(
proxyContent
).
toMatchInlineSnapshot
(
`
"// This file re-exports route types from the dev types location.
// This provides a stable import path for next-env.d.ts across dev/build modes.
export * from '../dev/types/routes.d.ts';
"
`
)
// The actual dev types should exist
expect
(
await
next
.
hasFile
(
'.next/dev/types/routes.d.ts'
)).
toBe
(
true
)
})
})
})
test/integration/custom-server-types/next-env.d.ts
View file @
42493fb3
/// <reference types="next" />
/// <reference types="next" />
/// <reference types="next/image-types/global" />
/// <reference types="next/image-types/global" />
import
'./.next/
dev/
types/routes.d.ts'
import
'./.next/types/routes.d.ts'
// NOTE: This file should not be edited
// NOTE: This file should not be edited
// see https://nextjs.org/docs/pages/api-reference/config/typescript for more information.
// see https://nextjs.org/docs/pages/api-reference/config/typescript for more information.
test/integration/typescript-app-type-declarations/next-env.d.ts
View file @
42493fb3
/// <reference types="next" />
/// <reference types="next" />
/// <reference types="next/image-types/global" />
/// <reference types="next/image-types/global" />
import
"./.next/
dev/
types/routes.d.ts"
;
import
"./.next/types/routes.d.ts"
;
// NOTE: This file should not be edited
// NOTE: This file should not be edited
// see https://nextjs.org/docs/pages/api-reference/config/typescript for more information.
// see https://nextjs.org/docs/pages/api-reference/config/typescript for more information.
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment