Skip to content

[Maintenance] Migrate Next.js 14 → 16 (supersedes dependabot PR #49) #51

Closed

Description

@PeterGuy326

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

  1. next lint is replaced. It was removed in Next 15; the test leg runs it and lint is now parsed as a project directory (Invalid project directory provided, no such directory: .../doc/lint, job 103580513817). Move linting to a standalone ESLint invocation wired into CI.
  2. The parallel route app/[locale]/work/[id]/@directory/ gets a default.js boundary. Turbopack treats its absence as a hard error: Missing required default.js file for parallel route at /[locale]/work/[id]/@directory (job 103580513625).
  3. The CSS file the new parser rejects is fixed. Under 14 the old parser warned through; under 16 Parsing CSS source code failed is fatal to the build.
  4. The fatal Module not found: Can't resolve 'proxy-agent' is resolved. It is an optional dependency reached from services/… code via new (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.
  5. The replacement PR is green on test, docker-build, CodeQL (javascript-typescript), Dependency review, and OpenSSF Scorecard, and is approved per CODEOWNERS before merge.

Validation plan

  • CI evidence on the replacement PR: linked test and docker-build job 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_approval and required_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

Activity

  1. added
    type:maintenanceReliability, security, release, or engineering maintenance
    status:readyScope and acceptance criteria are ready for implementation
    priority:p2Useful backlog work outside the immediate critical path
    dependenciesPull requests that update a dependency file
    on Sep 14, 2026
  2. waterbro-8 commented on Sep 18, 2026

    @waterbro-8
    Contributor

    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 to bytefolk/doc (push: false); a fork PR can follow if maintainers want that route.

  3. waterbro-8 commented on Sep 22, 2026

    @waterbro-8
    Contributor

    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 保持开放。

  4. waterbro-8 commented on Sep 22, 2026

    @waterbro-8
    Contributor

    更新:修复 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。

  5. PeterGuy326 commented on Oct 26, 2026

    @PeterGuy326
    ContributorAuthor

    Closing as completed — the tracked migration work is fully landed with git evidence:

    No open work remains under this issue's scope.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dependenciesPull requests that update a dependency filepriority:p2Useful backlog work outside the immediate critical pathstatus:readyScope and acceptance criteria are ready for implementationtype:maintenanceReliability, security, release, or engineering maintenance

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions