Docs: No longer any reference to next-env.d.ts in documentation

[nicolassanmar]

What is the improvement or update you wish to see?

I currently have an issue where the next-env.d.ts file is generating differently for me and other members of the team. We currently have this file commited in github.

The next-env.d.ts file points to https://nextjs.org/docs/pages/building-your-application/configuring/typescript, although there are not any references to the file, how it works, or how it is generated.

It appears that there was documentation about this before, and got removed: https://github.com/vercel/next.js/blob/v13.4.4/docs/basic-features/typescript.md#existing-projects. This suggested not commiting this file into source control, but now it does not make any suggestions.

I think we should add more documentation around this file, and at least add if we are supposed to commit this to source control or not. It's weird that the next-env.d.ts file redirects here without any information about it.

Is there any context that might help us understand?

I think this is a bug introduced in this commit https://github.com/vercel/next.js/pull/50701, where the documentation about the file got lost on the migration

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/pages/building-your-application/configuring/typescript

[Willem-Jaap]

I agree there should be some reference in the docs about this file. create-next-app has a gitignore containing next-env.d.ts

[MoOx]

This is indeed confusing. I recently updated my tsconfig and got issue on my CI because this file was missing. On my CI, I basically does this:

• npm ci
• eslint
• tsc --noEmit
• npm run build

To ensure my projet is in good shape. Problem is: next-env.d.ts is missing by default because it's gitignored by the default ts template. Which looks wrong.

I guess next lint handle this, but I just saw that this command is deprecated

`next lint` is deprecated and will be removed in Next.js 16.

There is also the recommended way to migrate, but it only affects eslint. So how are we supposed to handle this typescript file in the future?

[Willem-Jaap]

Run the build before tsc, then the file will be there and tsc will pass

npm ci
eslint
npm run build
tsc --noEmit

[icyJoseph]

You can also run npx next typegen and that'll set the next-env.d.ts file. One reason for its existence is to not have to do a full build to get types and such.

[Willem-Jaap]

I did not know that, thanks for that one 🙌

[icyJoseph]

And yes this is document, of course, given the confusion here, perhaps not as good as it should:

• https://nextjs.org/docs/app/api-reference/cli/next#next-lint-options

next lint generates a next-env.d.ts file, which is often needed during type-check. To ensure next-env.d.ts is present run next typegen before type-checking. next dev and next build also generate the next-env.d.ts file, but it is often undesirable to run these just to type-check.

I guess the typegen section should mention that, it outputs the next-env.d.ts

[kachkaev]

In Next 16.0.0, the contents of next-env.d.ts is non-determenistic.

Running next dev generates this:

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

// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

But running next build or next typegen generates this:

/// <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.

(note the /dev/ chunk on line 3)

Because next-env.d.ts depends on the last ran command, I added it to .gitignore. Doing so was impractical in the past because next typegen did not exist.

If you run ESLint or TSC, ensure the scripts include next typegen:

{
  "scripts": {
     "fix:eslint": "next typegen && eslint [...options...] --fix",
     "lint:eslint": "next typegen && eslint [...options...]",
     "lint:tsc": "next typegen && tsc [...options...]",
     "...": "..."
  }
}

[icyJoseph]

Oh great catch. What's happening here is that isolatedDevBuild outputs the dev server to .next/dev

We did add next-env.d.ts to .gitignore for create-next-app a while ago.

And yes next typegen is the way to go.

[kachkaev]

Can this be considered as closed via https://github.com/vercel/next.js/pull/85273?

[icyJoseph]

I believe so - sorry it took this long to stabilize docs around this file.

[github-actions[bot]]

This closed issue has been automatically locked because it had no new activity for 2 weeks. If you are running into a similar issue, please create a new issue with the steps to reproduce. Thank you.