Move next-env.d.ts to dist dir (#86752)

Author: huozhi

packages/next/src/build/index.ts

@@ -224,6 +224,7 @@ import {
   createRouteTypesManifest,
   writeRouteTypesManifest,
   writeValidatorFile,
+  writeDynamicTypesFile,
 } from '../server/lib/router-utils/route-types-utils'
 import { Lockfile } from './lockfile'
 import {
@@ -1484,6 +1485,12 @@ export default async function build(
             config
           )
           await writeValidatorFile(routeTypesManifest, validatorFilePath)
+          await writeDynamicTypesFile({
+            distDir,
+            imageImportsEnabled: !config.images.disableStaticImages,
+            hasPagesDir: !!pagesDir,
+            hasAppDir: !!appDir,
+          })
         })
 
       // Turbopack already handles conflicting app and page routes.

packages/next/src/build/type-check.ts

@@ -22,7 +22,6 @@ function verifyTypeScriptSetup(
   distDir: string,
   typeCheckPreflight: boolean,
   tsconfigPath: string | undefined,
-  disableStaticImages: boolean,
   cacheDir: string | undefined,
   enableWorkerThreads: boolean | undefined,
   hasAppDir: boolean,
@@ -52,7 +51,6 @@ function verifyTypeScriptSetup(
       distDir,
       typeCheckPreflight,
       tsconfigPath,
-      disableStaticImages,
       cacheDir,
       hasAppDir,
       hasPagesDir,
@@ -119,7 +117,6 @@ export async function startTypeChecking({
           config.distDir,
           !ignoreTypeScriptErrors,
           config.typescript.tsconfigPath,
-          config.images.disableStaticImages,
           cacheDir,
           config.experimental.workerThreads,
           !!appDir,

packages/next/src/cli/next-test.ts

@@ -142,7 +142,6 @@ async function runPlaywright(
       distDir: nextConfig.distDir,
       typeCheckPreflight: false,
       tsconfigPath: nextConfig.typescript.tsconfigPath,
-      disableStaticImages: nextConfig.images.disableStaticImages,
       hasAppDir: !!appDir,
       hasPagesDir: !!pagesDir,
       isolatedDevBuild: nextConfig.experimental.isolatedDevBuild,

packages/next/src/cli/next-typegen.ts

@@ -29,6 +29,7 @@ import {
   createRouteTypesManifest,
   writeRouteTypesManifest,
   writeValidatorFile,
+  writeDynamicTypesFile,
 } from '../server/lib/router-utils/route-types-utils'
 import { writeCacheLifeTypes } from '../server/lib/router-utils/cache-life-type-utils'
 import { createValidFileMatcher } from '../server/lib/find-page-file'
@@ -59,7 +60,6 @@ const nextTypegen = async (
     distDir: nextConfig.distDir,
     typeCheckPreflight: false,
     tsconfigPath: nextConfig.typescript.tsconfigPath,
-    disableStaticImages: nextConfig.images.disableStaticImages,
     hasAppDir: !!appDir,
     hasPagesDir: !!pagesDir,
     isolatedDevBuild: nextConfig.experimental.isolatedDevBuild,
@@ -171,6 +171,13 @@ const nextTypegen = async (
 
   await writeValidatorFile(routeTypesManifest, validatorFilePath)
 
+  await writeDynamicTypesFile({
+    distDir,
+    imageImportsEnabled: !nextConfig.images.disableStaticImages,
+    hasPagesDir: !!pagesDir,
+    hasAppDir: !!appDir,
+  })
+
   // Generate cache-life types if cacheLife config exists
   const cacheLifeFilePath = join(distDir, 'types', 'cache-life.d.ts')
   writeCacheLifeTypes(nextConfig.cacheLife, cacheLifeFilePath)

packages/next/src/lib/typescript/writeAppTypeDeclarations.ts

@@ -84,7 +84,6 @@ describe('writeConfigurationDefaults()', () => {
            "node_modules",
          ],
          "include": [
-           "next-env.d.ts",
            ".next/types/**/*.ts",
            ".next/dev/types/**/*.ts",
            "**/*.mts",
@@ -107,7 +106,7 @@ describe('writeConfigurationDefaults()', () => {
          	- strict was set to false
          	- noEmit was set to true
          	- incremental was set to true
-         	- include was set to ['next-env.d.ts', '.next/types/**/*.ts', '.next/dev/types/**/*.ts', '**/*.mts', '**/*.ts', '**/*.tsx']
+         	- include was set to ['.next/types/**/*.ts', '.next/dev/types/**/*.ts', '**/*.mts', '**/*.ts', '**/*.tsx']
          	- plugins was updated to add { name: 'next' }
          	- exclude was set to ['node_modules']
 

packages/next/src/lib/typescript/writeConfigurationDefaults.test.ts

@@ -282,19 +282,16 @@ export async function writeConfigurationDefaults(
   )
 
   if (!('include' in userTsConfig)) {
-    userTsConfig.include = hasAppDir
-      ? ['next-env.d.ts', ...nextAppTypes, '**/*.mts', '**/*.ts', '**/*.tsx']
-      : ['next-env.d.ts', '**/*.mts', '**/*.ts', '**/*.tsx']
+    // Always include .next/types for dynamic types (image imports, route types, etc.)
+    userTsConfig.include = [...nextAppTypes, '**/*.mts', '**/*.ts', '**/*.tsx']
     suggestedActions.push(
       cyan('include') +
         ' was set to ' +
         bold(
-          hasAppDir
-            ? `['next-env.d.ts', ${nextAppTypes.map((type) => `'${type}'`).join(', ')}, '**/*.mts', '**/*.ts', '**/*.tsx']`
-            : `['next-env.d.ts', '**/*.mts', '**/*.ts', '**/*.tsx']`
+          `[${nextAppTypes.map((type) => `'${type}'`).join(', ')}, '**/*.mts', '**/*.ts', '**/*.tsx']`
         )
     )
-  } else if (hasAppDir) {
+  } else {
     const missingFromResolved = []
     for (const type of nextAppTypes) {
       if (!userTsConfig.include.includes(type)) {

packages/next/src/lib/typescript/writeConfigurationDefaults.ts

@@ -9,7 +9,6 @@ import * as log from '../build/output/log'
 
 import { getTypeScriptIntent } from './typescript/getTypeScriptIntent'
 import type { TypeCheckResult } from './typescript/runTypeCheck'
-import { writeAppTypeDeclarations } from './typescript/writeAppTypeDeclarations'
 import { writeConfigurationDefaults } from './typescript/writeConfigurationDefaults'
 import { installDependencies } from './install-dependencies'
 import { isCI } from '../server/ci-info'
@@ -39,7 +38,6 @@ export async function verifyTypeScriptSetup({
   cacheDir,
   tsconfigPath,
   typeCheckPreflight,
-  disableStaticImages,
   hasAppDir,
   hasPagesDir,
   isolatedDevBuild,
@@ -52,7 +50,6 @@ export async function verifyTypeScriptSetup({
   cacheDir?: string
   tsconfigPath: string | undefined
   typeCheckPreflight: boolean
-  disableStaticImages: boolean
   hasAppDir: boolean
   hasPagesDir: boolean
   isolatedDevBuild: boolean | undefined
@@ -138,16 +135,6 @@ export async function verifyTypeScriptSetup({
       hasPagesDir,
       isolatedDevBuild
     )
-    // Write out the necessary `next-env.d.ts` file to correctly register
-    // Next.js' types:
-    await writeAppTypeDeclarations({
-      baseDir: dir,
-      distDir,
-      imageImportsEnabled: !disableStaticImages,
-      hasPagesDir,
-      hasAppDir,
-    })
-
     let result
     if (typeCheckPreflight) {
       const { runTypeCheck } =

packages/next/src/lib/verify-typescript-setup.ts

@@ -10,6 +10,7 @@ import {
   generateRouteTypesFile,
   generateLinkTypesFile,
   generateValidatorFile,
+  generateDynamicTypesFile,
 } from './typegen'
 import { tryToParsePath } from '../../../lib/try-to-parse-path'
 import {
@@ -382,3 +383,35 @@ export async function writeValidatorFile(
 
   await fs.promises.writeFile(filePath, generateValidatorFile(manifest))
 }
+
+/**
+ * Writes the dynamic types file (.next/types/next-env.d.ts) that contains
+ * config-dependent type references (image imports, navigation compat, etc.)
+ */
+export async function writeDynamicTypesFile({
+  distDir,
+  imageImportsEnabled,
+  hasPagesDir,
+  hasAppDir,
+}: {
+  distDir: string
+  imageImportsEnabled: boolean
+  hasPagesDir: boolean
+  hasAppDir: boolean
+}) {
+  const typesDir = path.join(distDir, 'types')
+  const filePath = path.join(typesDir, 'next-env.d.ts')
+
+  // Directory should already be created by writeRouteTypesManifest, but ensure it exists
+  if (!fs.existsSync(typesDir)) {
+    await fs.promises.mkdir(typesDir, { recursive: true })
+  }
+
+  const content = generateDynamicTypesFile({
+    imageImportsEnabled,
+    hasPagesDir,
+    hasAppDir,
+  })
+
+  await fs.promises.writeFile(filePath, content)
+}

packages/next/src/server/lib/router-utils/route-types-utils.ts

@@ -85,6 +85,7 @@ import {
   createRouteTypesManifest,
   writeRouteTypesManifest,
   writeValidatorFile,
+  writeDynamicTypesFile,
 } from './route-types-utils'
 import { writeCacheLifeTypes } from './cache-life-type-utils'
 import { isParallelRouteSegment } from '../../../shared/lib/segment'
@@ -145,7 +146,6 @@ async function verifyTypeScript(opts: SetupOpts) {
     distDir: opts.nextConfig.distDir,
     typeCheckPreflight: false,
     tsconfigPath: opts.nextConfig.typescript.tsconfigPath,
-    disableStaticImages: opts.nextConfig.images.disableStaticImages,
     hasAppDir: !!opts.appDir,
     hasPagesDir: !!opts.pagesDir,
     isolatedDevBuild: opts.nextConfig.experimental.isolatedDevBuild,
@@ -265,6 +265,12 @@ async function startWatcher(
     path.join(distTypesDir, 'routes.d.ts'),
     opts.nextConfig
   )
+  await writeDynamicTypesFile({
+    distDir,
+    imageImportsEnabled: !opts.nextConfig.images.disableStaticImages,
+    hasPagesDir: !!pagesDir,
+    hasAppDir: !!appDir,
+  })
 
   const routesManifestPath = path.join(distDir, ROUTES_MANIFEST)
   const routesManifest: DevRoutesManifest = {