Plan: Frontend Dependency Upgrade¶
Overview¶
Status: Done
Author: nguyenhuuca
Date: 2026-10-29
Tracking: docs/tracking.md row "Frontend Dependency Upgrade"; TASKS.md section "Frontend dependency upgrade"
Related PRD: PRD-frontend-deps-upgrade
Related ADR: ADR-0034
Spec: spec-frontend-deps-upgrade (cited as Rule n / FR-n / EC-n)
Sequence: sequence-frontend-deps-upgrade (flows 1–4)
Size: Small/Medium. 6 tasks; mostly manifest, lockfile and config changes. App code changes only if a new lint rule or a test-tooling change forces them.
Objective¶
Bring every webapp/ dependency to its latest release, remove the four unused @fortawesome/* packages, and build the webapp on Node 22 in CI, with no behaviour change for users.
| Package | From | To |
|---|---|---|
| vite | 6.4.1 | 8.3.5 |
| @vitejs/plugin-react | 4.7.0 | 6.1.2 |
| vitest | 3.2.4 | 5.0.5 |
| jsdom | 26.1.0 | 29.1.1 |
| @testing-library/jest-dom | 6.9.1 | 7.0.1 |
| eslint / @eslint/js | 9.39.4 | 10.13.0 / 10.0.1 |
| eslint-plugin-react-hooks | 5.2.0 | 7.1.1 |
| eslint-plugin-react-refresh | 0.4.26 | 0.5.7 |
| globals | 15.15.0 | 17.13.0 |
| react / react-dom | 19.2.4 | 19.3.1 |
| hls.js (exact pin) | 1.7.3 | 1.7.4 |
| other in-range packages | — | latest (spec FR-1) |
| @fortawesome/* (4) | — | removed |
| CI Node | 20 | 22 |
Scope¶
In Scope¶
- Spec FR-1 … FR-7: version bumps, FontAwesome removal, config adaptation, Node 22 in
deploy-web.ymlandautopilot.yml, docs (tech-strategy ×2, README), measurements in the commit body. - Local verification after each group, prod deploy and smoke.
Out of Scope¶
Same as the PRD: refactoring, new library APIs, replacing libraries, TypeScript, api/, landing/, Dependabot.
Technical Approach¶
Architecture Changes¶
None at runtime. Build pipeline changes from Vite 6 (Rollup) to Vite 8 (Rolldown); CI Node 20 → 22.
Key Decisions¶
- One commit, verified in groups (spec Rule 7). Each task FD-1 … FD-5 ends with the gates green and a local WIP commit; FD-6 squashes them with
git reset --soft <base>into one commit before asking to push. No interactive rebase. - Lockfile regenerated per group (EC-1):
rm -rf node_modules package-lock.json && npm install, thennpm cionce at the end. - No
--force/--legacy-peer-deps(EC-2). A peer conflict stops the task and goes to the owner. - Lint fallback per spec Rule 6 (≤ 10 local fixes, else
warn+TASKS.mdfollow-up; nevereslint-disable). - Order puts the cheap, low-risk group first, so a failure in the toolchain groups is clearly attributable.
Implementation Steps¶
Gates for every task (G): cd webapp && npm run lint && npx vitest run --root . && npm run build, then check dist/ for version.json, sw.js, manifest.json and a separate assets/hls-*.js.
Phase 1: Low-risk bumps¶
- FD-1 In-range packages (FR-1, Rules 3–4)
npm installthe latest of: react, react-dom, @types/react, @types/react-dom, @tanstack/react-query, react-router-dom, i18next, react-i18next, i18next-browser-languagedetector, @testing-library/react, @testing-library/user-event, cronstrue.- Set
"hls.js": "1.7.4"exactly. - G; WIP commit.
- FD-2 Remove FontAwesome (FR-4, Rule 2)
npm uninstallthe four@fortawesome/*packages;grep -r fortawesome webapp/srcreturns nothing.- G; WIP commit.
Phase 2: Toolchain majors¶
- FD-3 Build and test toolchain (FR-2, EC-3, EC-5)
- Bump vite 8, @vitejs/plugin-react 6, vitest 5, jsdom 29, @testing-library/jest-dom 7; regenerate lockfile.
- Apply only the migration-guide changes needed in
vite.config.js,vitest.config.js,src/test-setup.js. - Confirm the
version-fileplugin still emitsversion.jsonand__APP_BUILD__is defined;hlschunk still separate (sequence flows 3, 4). - Record main chunk gzip size (target ≤ 258.8 kB).
- G; WIP commit.
- FD-4 Lint toolchain (FR-3, Rule 6, EC-4)
- Bump eslint 10, @eslint/js 10, eslint-plugin-react-hooks 7, eslint-plugin-react-refresh 0.5, globals 17.
- Adapt
eslint.config.jsto the react-hooks 7 config export (currently spreadsreactHooks.configs.recommended.rules). - Count new errors per rule; apply Rule 6. Add
TASKS.mdfollow-ups for any rule set towarn. - G; WIP commit.
Phase 3: CI, docs, land¶
- FD-5 Node 22 and docs (FR-5, FR-6, Rule 8)
deploy-web.ymlandautopilot.yml:node-version: '22'..claude/rules/tech-strategy.md+docs/claude/rules/tech-strategy.md: Vite 8, hls.js 1.7.4.README.md: Build Tool → Vite 8; Icons → Material Symbols Outlined.- WIP commit.
- FD-6 Land and verify (Rule 1, Rule 7, FR-7)
npm outdatedempty;npm cifrom the lockfile; final G.- Squash WIP commits into one with measurements in the body (chunk sizes, lint warnings,
npm auditcounts). - Update
TASKS.md,docs/tracking.md,session.txt. - Ask the owner before
git push; watch "Deploy Frontend (React Build)"; owner prod smoke.
Files to Modify¶
| File | Change |
|---|---|
webapp/package.json, webapp/package-lock.json |
Versions, FontAwesome removed, lockfile regenerated |
webapp/vite.config.js |
Only if Vite 8 / plugin-react 6 require it |
webapp/vitest.config.js, webapp/src/test-setup.js |
Only if Vitest 5 / jsdom 29 / jest-dom 7 require it |
webapp/eslint.config.js |
ESLint 10 / react-hooks 7 config shape; possible warn overrides |
webapp/src/** |
Only local fixes for new lint rules or tooling-driven test edits |
.github/workflows/deploy-web.yml, .github/workflows/autopilot.yml |
Node 22 |
.claude/rules/tech-strategy.md, docs/claude/rules/tech-strategy.md, README.md |
Versions, icon row |
TASKS.md, docs/tracking.md, session.txt |
Status |
Dependencies¶
Code Dependencies¶
- Vite 7 + 8, Vitest 4 + 5, ESLint 10, eslint-plugin-react-hooks 7 migration guides (read before FD-3 / FD-4; verify via Context7 per Core Principle 1).
Service Dependencies¶
- GitHub Actions
actions/setup-node@v4with Node 22.
Testing Strategy¶
Unit Tests¶
Existing 76 Vitest files / 655 tests are the regression suite; none skipped or deleted (Rule 5). No new tests: the change adds no behaviour.
Integration Tests¶
Build-output checks after FD-3 and FD-6: dist/version.json, dist/sw.js, dist/manifest.json, separate dist/assets/hls-*.js; main chunk ≤ 258.8 kB gzip.
Manual Testing¶
Prod smoke after deploy: login, feed, HLS playback and Range fallback, admin pages, language switch, PWA new-version banner.
Rollback Plan¶
git revert <commit> and push (with owner approval); "Deploy Frontend" redeploys the previous build. No data or API change to undo.
Risks¶
| Risk | Mitigation |
|---|---|
| Rolldown changes chunks or plugin hooks | FD-3 output checks; EC-3 blocks on missing hls chunk or version.json |
| react-hooks 7 floods lint | Rule 6 threshold and warn fallback |
| Test tooling semantics change | EC-5: adapt API usage, keep assertions |
| Peer conflicts | EC-2: stop, no --force |
| Node 22 CI-only failure | EC-6: reproduce under Node 22 locally |
Checklist¶
Before Starting¶
- [x] PRD approved, ADR-0034 accepted, spec + sequence written
- [ ] Baseline recorded (spec "Baseline" table)
- [ ] Working tree clean in
webapp/
Before PR¶
- [ ] All spec Acceptance Criteria pass locally
- [ ] Single squashed commit with measurements
Before Merge¶
- [ ] Owner approves push
- [ ] "Deploy Frontend" green, prod smoke passed
Notes¶
Commit lands directly on main (repo convention); "Before PR" means "before asking to push".
Progress Log¶
| Date | Task | Note |
|---|---|---|
| 2026-10-29 | — | Plan written |
| 2026-10-29 | FD-1..FD-5 | Built by autopilot, squashed to 82be7105 |
| 2026-10-29 | FD-6 | Deploy Frontend green on Node 22, owner prod smoke pass |