next-env.d.ts changes route type import between next dev and next typegen

[IFAKA]

Link to the code that reproduces this issue

https://github.com/IFAKA/next-env-dts-churn-repro

To Reproduce

The repro is based on the official reproduction-template, uses TypeScript/App Router, and intentionally tracks next-env.d.ts so the generated-file churn is visible as a Git diff.

npm run typecheck
sed -n '1,6p' next-env.d.ts
npm run dev
# stop dev after Ready
sed -n '1,6p' next-env.d.ts
git diff -- next-env.d.ts
npm run typecheck
sed -n '1,6p' next-env.d.ts

The added script is:

"typecheck": "next typegen && tsc --noEmit"

Current vs. Expected behavior

Current behavior: the root generated next-env.d.ts changes depending on command order.

After next typegen / npm run typecheck:

/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/types/routes.d.ts";
import "./.next/types/root-params.d.ts";

After next dev:

/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/dev/types/routes.d.ts";
import "./.next/dev/types/root-params.d.ts";

Observed diff after starting next dev from a committed next typegen baseline:

diff --git a/next-env.d.ts b/next-env.d.ts
index ce4e94a..a419cbe 100644
--- a/next-env.d.ts
+++ b/next-env.d.ts
@@ -1,7 +1,7 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
-import "./.next/types/root-params.d.ts";
+import "./.next/dev/types/routes.d.ts";
+import "./.next/dev/types/root-params.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

Running npm run typecheck again passes and flips the imports back to .next/types/....

Expected behavior: either the generated root next-env.d.ts output stays stable across local commands, or docs/tooling more clearly guide users toward ignoring the file and running next typegen before standalone tsc.

I know the docs already recommend ignoring next-env.d.ts:

• TypeScript docs: https://nextjs.org/docs/app/api-reference/config/typescript#next-envdts
• Project structure docs: https://nextjs.org/docs/app/getting-started/project-structure

That mitigation works locally. This issue is for the churn that still appears when a project has historically tracked the file, which makes next dev and next typegen fight over the checked-in content.

Related context:

• keep next-env.d.s unchanged between dev and build #88428 attempted to keep next-env.d.ts stable between dev and build/typegen.
• Revert "keep next-env.d.s unchanged between dev and build" #90384 reverted that change after it caused incomplete/inconsistent generated types and notes that the recommendation is still to ignore next-env.d.ts.

Provide environment information

From the repro with Node 25.6.1:

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.5.0: Mon Apr 27 20:41:15 PDT 2026; root:xnu-12377.121.6~2/RELEASE_ARM64_T6041
  Available memory (MB): 49152
  Available CPU cores: 12
Binaries:
  Node: 25.6.1
  npm: 11.12.1
  Yarn: 1.22.22
  pnpm: 10.25.0
Relevant Packages:
  next: 16.3.0-canary.30 // Latest available version is detected (16.3.0-canary.30).
  eslint-config-next: N/A
  react: 19.2.6
  react-dom: 19.2.6
  typescript: 5.9.3
Next.js Config:
  output: N/A

Additional project evidence where this was noticed:

Declared Next range: ^16.1.0
Installed Next version: 16.2.6
Node: 25.6.1
TypeScript: 5.9.3

Which area(s) are affected? (Select all that apply)

TypeScript

Which stage(s) are affected? (Select all that apply)

next dev (local), Other (next typegen)

Additional context

This is intentionally not a PR because the previous stability fix in #88428 was reverted in #90384 after causing generated type correctness issues. A docs/tooling clarification may be safer than changing the generated import target again, but I wanted to provide a current canary repro for the remaining churn.

[icyJoseph]

This is intentionally not a PR because the previous stability fix in #88428 was reverted in #90384 after causing generated type correctness issues.

IIRC the initial fix, make other things break...

What is it that you are after here? We already recommend ignoring the file, short of expecting it to be ignored to be honest. It has been some weeks since I looked at this.

[IFAKA]

Yeah, that makes sense. I am not asking to bring #88428 back as-is, especially given the type correctness issues that led to #90384.

What I was after is mostly a clearer contract for next-env.d.ts.

If the intended answer is "this file is generated, command-specific, and should not be tracked", then I think this can be closed as expected behavior.

The part that confused me in an existing repo was the command-order churn:

• next dev rewrites it to .next/dev/types/...
• next typegen / build rewrites it to .next/types/...
• standalone tsc --noEmit needs next typegen first if it relies on generated route types

The docs already say to ignore next-env.d.ts, but I did not understand from the docs that the file can legitimately switch between those import targets depending on the command.

A small docs note would have been enough for me. A warning when Next rewrites a tracked next-env.d.ts would also help existing repos, but I am not blocked on that if the contract is simply that tracked next-env.d.ts is unsupported.

[icyJoseph]

No worries. I think around v12, the wording around next-env.d.ts was like, we reserve the right to write, and output changes to it, so it is better to have it outside version control. I am thinking changing the https://nextjs.org/docs/app/api-reference/config/typescript#next-envdts to:

## `next-env.d.ts`

Next.js generates a `next-env.d.ts` file in your project root. This file references Next.js type definitions, allowing TypeScript to recognize non-code imports (images, stylesheets, etc.) and Next.js-specific types.

Running `next dev`, `next build`, or [`next typegen`](/docs/app/api-reference/cli/next#next-typegen-options) regenerates this file.

> **Good to know**:
>
> - `next-env.d.ts` is a file managed by Next.js. Its contents are an implementation detail and may change over time. To avoid unnecessary diffs, we recommend excluding it from version control. Do not edit this file manually.
> - The file must be in your `tsconfig.json` `include` array (`create-next-app` does this automatically).

Something like that... it should be good enough I think - we want to just cover this scenario, I see this next-env.d.ts file producing git diffs - what does the docs say about this?

[IFAKA]

No worries, that makes sense.

I think that docs wording would cover the confusing case I hit. The key bit for me is just making it clear that next-env.d.ts is managed by Next.js, can be regenerated by different commands, and should stay out of version control.

I’m good with treating this as expected behavior / docs clarification.
I’ll leave the issue open for you folks to close or retag however makes sense.

Thanks!