From ae7355a1db38bc36be6060c294530b9e3a626991 Mon Sep 17 00:00:00 2001 From: Shannon Anahata Date: Fri, 13 Mar 2026 15:18:07 -0700 Subject: [PATCH 1/6] docs(repo): Document next-env.d.ts behavior and restore workflow Explain why next-env.d.ts often shows as modified (Next.js regenerates it), that 'git restore next-env.d.ts' is safe, and how it differs from lockfiles. Add long-term note: once the repo upgrades to Next 15.5+, add next-env.d.ts to .gitignore and run 'next typegen' before type-check for the recommended approach; current Next 15.1.x does not expose the typegen CLI. Made-with: Cursor --- AGENTS.md | 10 ++++++++++ CONTRIBUTING.md | 4 ++++ 2 files changed, 14 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ebc63ce7ca7b3..dfc50fc3cee9a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,6 +52,16 @@ Run `pnpm test` for vitest. Tests live alongside source files or in `__tests__` | `pnpm lint:eslint` | ESLint check | | `pnpm lint:prettier` | Prettier check | +## Repo UX / Generated files + +### `next-env.d.ts` showing as modified + +`next-env.d.ts` is **auto-generated by Next.js** (see the "should not be edited" note in the file). Running `pnpm dev` or `pnpm build` can regenerate it with slightly different content (e.g. a reference to `.next/types/routes.d.ts`), so it often appears as modified after local runs. + +- **What to do:** Run `git restore next-env.d.ts` to discard local changes when you don't intend to commit that file. It will not break anything. +- **Why this is different from lockfiles:** Lockfiles (`pnpm-lock.yaml`, `yarn.lock`) are **meant to be committed and updated**. They record exact dependency versions so installs are reproducible; when someone runs `pnpm add` or `yarn add`, the lockfile change is intentional and gets committed so everyone stays in sync. By contrast, `next-env.d.ts` is a **build/tooling artifact** that Next.js regenerates; its contents can vary by environment and last command run, so committing it causes unnecessary churn and merge noise. +- **Long-term fix (when upgrading to Next 15.5+):** The recommended approach is to add `next-env.d.ts` to `.gitignore` and run `next typegen` before type-check (e.g. in `lint:ts` and CI). The current Next version in this repo does not yet expose the `next typegen` CLI, so for now the file remains tracked and contributors can restore it when it shows as modified. + ## Developer Documentation (develop-docs/) When writing requirements in `develop-docs/`: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6818dc5e118e1..447fe2490d129 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,3 +19,7 @@ pnpm dev:developer-docs ``` With that, the repo is fully set up and you are ready to open local docs under http://localhost:3000 + +### If `next-env.d.ts` shows as modified + +That file is auto-generated by Next.js. You can run `git restore next-env.d.ts` to discard the change; see AGENTS.md ("Repo UX / Generated files") for why and for the long-term approach. From 5c4c564ae4fae6f92043c1b980dc72ae4594eafd Mon Sep 17 00:00:00 2001 From: Shannon Anahata Date: Fri, 13 Mar 2026 15:27:29 -0700 Subject: [PATCH 2/6] chore(repo): Add next-env.d.ts to .gitignore and stop tracking File is auto-generated by Next.js on pnpm dev / pnpm build. Ignoring it prevents local churn; everyone gets the same .gitignore via this PR. Made-with: Cursor --- .gitignore | 1 + next-env.d.ts | 7 ------- 2 files changed, 1 insertion(+), 7 deletions(-) delete mode 100644 next-env.d.ts diff --git a/.gitignore b/.gitignore index 87bf346528193..8763df8b47941 100644 --- a/.gitignore +++ b/.gitignore @@ -73,6 +73,7 @@ linkcheck # next.js /.next/ /out/ +next-env.d.ts public/~partytown public/page-data diff --git a/next-env.d.ts b/next-env.d.ts deleted file mode 100644 index 36a4fe488ad02..0000000000000 --- a/next-env.d.ts +++ /dev/null @@ -1,7 +0,0 @@ -/// -/// -/// -/// - -// NOTE: This file should not be edited -// see https://nextjs.org/docs/app/api-reference/config/typescript for more information. From 6bfd74ec8fc01958a9057f02c0c52b9e854f9fe2 Mon Sep 17 00:00:00 2001 From: Shannon Anahata Date: Fri, 13 Mar 2026 15:45:04 -0700 Subject: [PATCH 3/6] ci: Generate next-env.d.ts before type-check; shorten docs - Add pnpm next build before lint:ts in test workflow so type-check passes when next-env.d.ts is gitignored. Replace with next typegen on Next 15.5+. - Shorten next-env.d.ts messaging in AGENTS.md and CONTRIBUTING.md. Made-with: Cursor --- .github/workflows/test.yml | 3 +++ AGENTS.md | 8 +------- CONTRIBUTING.md | 4 +--- 3 files changed, 5 insertions(+), 10 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 31b9478ca7f35..c0f2374d804d4 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -40,6 +40,9 @@ jobs: - run: pnpm install --frozen-lockfile + # Generate next-env.d.ts (in .gitignore); required before type-check. Replace with `next typegen` when on Next 15.5+ + - run: pnpm next build + # Additional checks - run: pnpm lint:ts diff --git a/AGENTS.md b/AGENTS.md index dfc50fc3cee9a..cdfde89f3df8c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,13 +54,7 @@ Run `pnpm test` for vitest. Tests live alongside source files or in `__tests__` ## Repo UX / Generated files -### `next-env.d.ts` showing as modified - -`next-env.d.ts` is **auto-generated by Next.js** (see the "should not be edited" note in the file). Running `pnpm dev` or `pnpm build` can regenerate it with slightly different content (e.g. a reference to `.next/types/routes.d.ts`), so it often appears as modified after local runs. - -- **What to do:** Run `git restore next-env.d.ts` to discard local changes when you don't intend to commit that file. It will not break anything. -- **Why this is different from lockfiles:** Lockfiles (`pnpm-lock.yaml`, `yarn.lock`) are **meant to be committed and updated**. They record exact dependency versions so installs are reproducible; when someone runs `pnpm add` or `yarn add`, the lockfile change is intentional and gets committed so everyone stays in sync. By contrast, `next-env.d.ts` is a **build/tooling artifact** that Next.js regenerates; its contents can vary by environment and last command run, so committing it causes unnecessary churn and merge noise. -- **Long-term fix (when upgrading to Next 15.5+):** The recommended approach is to add `next-env.d.ts` to `.gitignore` and run `next typegen` before type-check (e.g. in `lint:ts` and CI). The current Next version in this repo does not yet expose the `next typegen` CLI, so for now the file remains tracked and contributors can restore it when it shows as modified. +`next-env.d.ts` is in `.gitignore` and is generated by Next.js when you run `pnpm dev` or `pnpm build`. When we upgrade to Next 15.5+, we can run `next typegen` in CI and in `lint:ts` so the file is generated before type-check. ## Developer Documentation (develop-docs/) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 447fe2490d129..d7943a39b3d81 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,6 +20,4 @@ pnpm dev:developer-docs With that, the repo is fully set up and you are ready to open local docs under http://localhost:3000 -### If `next-env.d.ts` shows as modified - -That file is auto-generated by Next.js. You can run `git restore next-env.d.ts` to discard the change; see AGENTS.md ("Repo UX / Generated files") for why and for the long-term approach. +`next-env.d.ts` is in `.gitignore` and is generated when you run `pnpm dev` or `pnpm build`. When we upgrade to Next 15.5+, we can run `next typegen` in CI and in `lint:ts` so the file is generated before type-check. From 584ecc387d7fa032e0da1db30ca95ec649e14785 Mon Sep 17 00:00:00 2001 From: Shannon Anahata Date: Fri, 13 Mar 2026 15:49:17 -0700 Subject: [PATCH 4/6] build: Skip NEXT_PUBLIC_SENTRY_DSN check in CI Allow next build to run in GitHub Actions without a DSN so we can generate next-env.d.ts for type-check. Production and local builds still require the env. Made-with: Cursor --- next.config.ts | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/next.config.ts b/next.config.ts index 32aa844901692..5377d6f5284bb 100644 --- a/next.config.ts +++ b/next.config.ts @@ -87,7 +87,11 @@ const outputFileTracingIncludes = process.env.NEXT_PUBLIC_DEVELOPER_DOCS 'sitemap.xml': ['public/doctree.json'], }; -if (process.env.NODE_ENV !== 'development' && !process.env.NEXT_PUBLIC_SENTRY_DSN) { +if ( + process.env.NODE_ENV !== 'development' && + !process.env.NEXT_PUBLIC_SENTRY_DSN && + !process.env.GITHUB_ACTIONS +) { throw new Error( 'Missing required environment variable: NEXT_PUBLIC_SENTRY_DSN must be set in production' ); From 5173d1e5cbc4f49bff691804d1f3fc787a5c59bb Mon Sep 17 00:00:00 2001 From: Shannon Anahata Date: Fri, 13 Mar 2026 16:08:02 -0700 Subject: [PATCH 5/6] ci: Use build + doctree for next-env.d.ts; narrow DSN bypass to NEXT_TYPEGEN - Run enforce-redirects and generate-doctree before next build so CI build succeeds (doctree.json required for sitemap). typegen not available in current Next. - Bypass DSN check only when NEXT_TYPEGEN is set (typegen/build step), not all GITHUB_ACTIONS, so other workflows still validate Sentry config. Made-with: Cursor --- .github/workflows/test.yml | 6 ++++-- next.config.ts | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index c0f2374d804d4..0ddc29c1c1587 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -40,8 +40,10 @@ jobs: - run: pnpm install --frozen-lockfile - # Generate next-env.d.ts (in .gitignore); required before type-check. Replace with `next typegen` when on Next 15.5+ - - run: pnpm next build + # Generate next-env.d.ts (in .gitignore); required before type-check. Use full build deps (doctree) so next build succeeds. Switch to `next typegen` when on Next 15.5+ + - run: pnpm enforce-redirects && pnpm generate-doctree && pnpm next build + env: + NEXT_TYPEGEN: 'true' # Additional checks - run: pnpm lint:ts diff --git a/next.config.ts b/next.config.ts index 5377d6f5284bb..9b53988f208e8 100644 --- a/next.config.ts +++ b/next.config.ts @@ -90,7 +90,7 @@ const outputFileTracingIncludes = process.env.NEXT_PUBLIC_DEVELOPER_DOCS if ( process.env.NODE_ENV !== 'development' && !process.env.NEXT_PUBLIC_SENTRY_DSN && - !process.env.GITHUB_ACTIONS + !process.env.NEXT_TYPEGEN ) { throw new Error( 'Missing required environment variable: NEXT_PUBLIC_SENTRY_DSN must be set in production' From ec2a85ae4c06871a47a12a42a7401e62b42b379f Mon Sep 17 00:00:00 2001 From: Shannon Anahata Date: Fri, 13 Mar 2026 16:29:41 -0700 Subject: [PATCH 6/6] ci: Use next typegen instead of full build for next-env.d.ts Generates type definitions only; no doctree or full build. Repo is on Next 15.5. Made-with: Cursor --- .github/workflows/test.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 0ddc29c1c1587..c5b55e19b949a 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -40,8 +40,8 @@ jobs: - run: pnpm install --frozen-lockfile - # Generate next-env.d.ts (in .gitignore); required before type-check. Use full build deps (doctree) so next build succeeds. Switch to `next typegen` when on Next 15.5+ - - run: pnpm enforce-redirects && pnpm generate-doctree && pnpm next build + # Generate next-env.d.ts (in .gitignore); required before type-check + - run: pnpm next typegen env: NEXT_TYPEGEN: 'true'