Add gitignore note for next-env.d.ts

[icyJoseph]

---

Slack Thread

 

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[eps1lon]

.env* files should also not be tracked

[hernan-yadiel]

Hey, I just came across this PR because I was wondering if this file should be tracked by version control. I ultimately decided to track it because I saw this 4 years old comment in a GH issue by one Next.js core team member: #26533 (comment)

Can you please explain me why it shouldn't be tracked? Its content almost never changes, so it seems reasonable, for me, to track it.

[icyJoseph]

@hernan-yadiel - #39051

It is a recommendation after all, but do consider that, Next.js can publish and update type signatures on that file. For example with the introduction of https://nextjs.org/docs/app/api-reference/config/next-config-js/isolatedDevBuild, or route props helpers, etc.

• https://nextjs.org/docs/13/app/building-your-application/upgrading/from-vite#step-8-update-scripts-in-packagejson
• Move styled-jsx type reference #37964

A file named next-env.d.ts will be created in the root of your project. This file ensures Next.js types are picked up by the TypeScript compiler. You cannot remove it or edit it as it can change at any time. As such this file should not be committed and should be ignored by version control.

[chrisweb]

@icyJoseph I was not sure where to put this :/ so I post it here. The problem I encountered was that with Next.js 16, when adding a static image (using an import), linting in ci would start failing. The problem with ci was that next-env.d.ts did not exist, because it did not exist typescript would not have access to next/image-types/global, and ended up throwing an error. So instead of just running linting and then build, you actually need to run "next typegen", then linting and finally build.

I am not sure this is due to the fact that next.js 16 does not handle linting during builds on its own anymore or because of the new isolatedDevBuild!?

I am glad I found your comment here #85738 (comment) else I would not have known about the next typegen command.

When I asked the AI it either removed the next-env.d.ts from .gitignore (bad) or it create a new types file that containing similar types to what is in next/image-types/global and then add them to tsconfig (bad). I have a feeling other users will run into this, so maybe a docs update would be good? Maybe in here https://nextjs.org/docs/app/getting-started/installation#set-up-linting?

[icyJoseph]

@chrisweb we do mention here, https://nextjs.org/docs/app/api-reference/cli/next#next-typegen-options:

Additionally, next typegen generates a next-env.d.ts file. We recommend adding next-env.d.ts to your .gitignore file.

The next-env.d.ts file is included into your tsconfig.json file, to make Next.js types available to your project.

To ensure next-env.d.ts is present before type-checking run next typegen. The commands 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, for example in CI/CD environments.

That being said, yes, we need to improve discoverability of this. next lint was removed in 16.

• https://nextjs.org/docs/app/guides/upgrading/version-16#next-lint-command
• https://nextjs.org/blog/next-15-5#next-typegen

I'll add more signposts to discover typegen

[chrisweb]

I'll add more signposts to discover typegen

Yes, that would be great 👍

@icyJoseph (and now that I have already misused this PR, I just wanted to say thank you for the many useful posts and comments I have read from you over the years, they helped me countless times :) )