Repository navigation
[Maintenance] Migrate Next.js 14 → 16 (supersedes dependabot PR #49) #51
Copy link
Copy link
Closed
Labels
dependenciesPull requests that update a dependency filePull requests that update a dependency filepriority:p2Useful backlog work outside the immediate critical pathUseful backlog work outside the immediate critical pathstatus:readyScope and acceptance criteria are ready for implementationScope and acceptance criteria are ready for implementationtype:maintenanceReliability, security, release, or engineering maintenanceReliability, security, release, or engineering maintenance
Description
Preflight
- I searched open and closed issues for duplicate work.
Motivation
Dependabot PR #49 proposed bumping next from 14.2.35 to 16.3.5 with a one-line manifest change and zero source changes. Both CI legs fail for reasons that can only be fixed by source changes, so the PR cannot go green in its current shape — it is a framework migration wearing a bump's clothing. Two major versions (14 → 15 → 16) separate the current runtime from the target, and the repo gains nothing from keeping the bump open while the migration work is unowned. The PR was closed; this issue tracks the real work.
Evidence: #49 (comment) (reading of head 58edfb50117, CI job logs quoted verbatim there).
Scope
In scope:
- The four source-level breakages listed in the acceptance criteria below.
- One replacement upgrade PR carrying the manifest/lock bump plus those source changes.
Out of scope:
- Other dependency upgrades bundled into the same PR.
- Redesigning the affected route or its rendering model beyond what Next 16 forces.
Acceptance criteria
next lintis replaced. It was removed in Next 15; thetestleg runs it andlintis now parsed as a project directory (Invalid project directory provided, no such directory: .../doc/lint, job103580513817). Move linting to a standalone ESLint invocation wired into CI.- The parallel route
app/[locale]/work/[id]/@directory/gets adefault.jsboundary. Turbopack treats its absence as a hard error:Missing required default.js file for parallel route at /[locale]/work/[id]/@directory(job103580513625). - The CSS file the new parser rejects is fixed. Under 14 the old parser warned through; under 16
Parsing CSS source code failedis fatal to the build. - The fatal
Module not found: Can't resolve 'proxy-agent'is resolved. It is an optional dependency reached fromservices/…code vianew (require('proxy-agent'))(proxy); 16's bundler treats the unresolved require as fatal where 14 left it as a dynamic require. Either declare the dependency explicitly or guard the require. - The replacement PR is green on
test,docker-build,CodeQL (javascript-typescript),Dependency review, andOpenSSF Scorecard, and is approved per CODEOWNERS before merge.
Validation plan
- CI evidence on the replacement PR: linked
testanddocker-buildjob runs, both success. - Follow the Next.js 14 → 15 and 15 → 16 upgrade guides (codemods where applicable) in order; record in the PR body which codemods were run and which breakages needed manual changes.
- Reviewer approval from a CODEOWNER who is not the PR author (this repo enforces
require_last_push_approvalandrequired_conversation_resolution; approval must post-date the final push).
Affected component
Next.js web app runtime, services/collaboration bundling, CI lint step.
Dependencies and risks
- Supersedes chore(deps): bump next from 14.2.35 to 16.3.5 #49 (closed, not merged).
- Pre-existing, not owned by this task: the chore(deps): bump next from 14.2.35 to 16.3.5 #49 log also reported
67 vulnerabilities (53 moderate, 14 high)from the pre-build audit. - Rollback: the upgrade is a single PR; reverting it restores the Next 14 runtime.
Metadata
Metadata
Assignees
Labels
dependenciesPull requests that update a dependency filePull requests that update a dependency filepriority:p2Useful backlog work outside the immediate critical pathUseful backlog work outside the immediate critical pathstatus:readyScope and acceptance criteria are ready for implementationScope and acceptance criteria are ready for implementationtype:maintenanceReliability, security, release, or engineering maintenanceReliability, security, release, or engineering maintenance
Activity
waterbro-8 commentedon Sep 18, 2026
No replacement Next 14→16 PR is open. Closed #49 was a lockfile-only bump and failed on the four source breakages listed in this issue (
next lint,@directory/default.js, CSS parse,proxy-agent).I am not shipping another lockfile-only bump. A valid PR has to carry those source changes plus green
test/docker-build/ CodeQL / Dependency review / Scorecard. This account cannot push tobytefolk/doc(push: false); a fork PR can follow if maintainers want that route.waterbro-8 commentedon Sep 22, 2026
Next 16 实现 PR #76 已合入,但当前 main push run 35496401031 并非全绿:67 files / 350 tests 的断言全部通过后,share-doc-button.test.tsx 在 JSDOM teardown 阶段触发 React 19 未捕获异步 commit。根因是 Vitest globals 关闭时 React Testing Library 未自动注册 cleanup。修复已提 PR #84:#84 。在 #84 hosted CI 通过并合入前,本 issue 保持开放。
waterbro-8 commentedon Sep 22, 2026
更新:修复 PR #84 的 exact head dcfb0d2 已完成 hosted 验证。test(含 format、lint、test-ci、Playwright、collaboration build、CLI check、Next build)、docker-build、Dependency review、Scorecard 均通过;fork CodeQL 按平台规则 skipped。PR 当前仅剩正式 review/merge,合入后即可重新验证 main 并关闭本 issue。
PeterGuy326 commentedon Oct 26, 2026
Closing as completed — the tracked migration work is fully landed with git evidence:
b1036380, 2026-09-20).maincurrently runsnext@16.4.3(bumped via chore(deps): bump next from 16.3.5 to 16.3.8 #112 → chore(deps): bump next from 16.3.8 to 16.4.3 #125), withtest/docker-buildgreen on every merge since.c298143e;main'svitestSetup.tsalready registersafterEach(cleanup).No open work remains under this issue's scope.