Feature Specification: Frontend Dependency Upgrade¶
Metadata¶
Status: Approved
Author: nguyenhuuca (with Claude Code /spec)
Date: 2026-10-29
Related PRD: PRD-frontend-deps-upgrade
Related ADR: ADR-0034
Sequence diagrams: sequence-frontend-deps-upgrade
Overview¶
Every dependency in webapp/package.json moves to its latest release (23 packages) or is removed (4 unused @fortawesome/* packages), and every CI job that installs or builds webapp/ runs on Node 22. The built SPA must behave exactly as before for viewers and admins; only the toolchain, configuration files and test setup change where a migration requires it.
Baseline (measured 2026-10-29, before the upgrade)¶
| Measure | Value | How |
|---|---|---|
| Outdated packages | 27 | npm outdated |
Main JS chunk assets/index-*.js |
798.54 kB, 246.44 kB gzip | npm run build output |
Lazy assets/hls-*.js chunk |
595.01 kB, 185.84 kB gzip | npm run build output |
CSS assets/index-*.css |
298.97 kB, 43.13 kB gzip | npm run build output |
dist/ top level |
assets/, icons/, index.html, manifest.json, sw.js, version.json |
ls dist |
| Build time (local, Node 24) | 6.25 s (Vite), 8.5 s wall | time npm run build |
| Lint | 0 errors, 3 warnings (react-refresh/only-export-components) |
npm run lint |
| Tests | 76 files, 655 tests, all pass | npx vitest run --root . |
npm audit |
16 (1 low, 3 moderate, 10 high, 2 critical) | npm audit |
Business Rules¶
Rule 1: Everything current¶
After the change, cd webapp && npm outdated prints nothing.
Rule 2: Unused packages are removed, not upgraded¶
@fortawesome/free-brands-svg-icons, @fortawesome/free-regular-svg-icons, @fortawesome/free-solid-svg-icons and @fortawesome/react-fontawesome are deleted from package.json and the lockfile. No source file imports them before or after.
Rule 3: hls.js is pinned exactly¶
package.json contains "hls.js": "1.7.4" with no range operator (ADR-0031 intent kept).
Rule 4: Other ranges use caret¶
Every other dependency uses a ^<latest> range, matching the file's current style.
Rule 5: No test is skipped or deleted¶
All 76 test files and the 655 tests from the baseline still exist and pass. A test may be edited only where the new test tooling changes an API it uses, and the assertion it makes must stay the same.
Rule 6: Lint rule fallback threshold¶
For new rules introduced by eslint-plugin-react-hooks 7: if the total number of new errors is ≤ 10 and each can be fixed locally (inside one function or hook, without changing a component's structure or props), fix them. If there are > 10, or any one needs refactoring, set each affected rule to warn in eslint.config.js and add one follow-up line per rule to TASKS.md. Per-line eslint-disable comments are not allowed.
Rule 7: One commit, verified in groups¶
The change lands as one commit on main, but the builder runs the gates after each package group (Plan tasks) and does not squash until every group is green.
Rule 8: Same Node everywhere in CI¶
deploy-web.yml and the webapp setup step in autopilot.yml both use node-version: '22'. No workflow that runs npm ci in webapp/ stays on 20.
Functional Requirements¶
FR-1: In-range upgrades¶
The system must move these packages to latest: react, react-dom 19.3.1; @types/react, @types/react-dom 19.3.0; @tanstack/react-query 5.105.0; react-router-dom 7.18.5; i18next 26.5.11; react-i18next 17.1.9; i18next-browser-languagedetector 8.2.3; @testing-library/react 16.3.3; @testing-library/user-event 14.6.8; cronstrue 3.38.0; hls.js 1.7.4 (exact).
FR-2: Build and test toolchain¶
The system must move vite to 8.x, @vitejs/plugin-react to 6.x, vitest to 5.x, jsdom to 29.x and @testing-library/jest-dom to 7.x, and update vite.config.js, vitest.config.js and src/test-setup.js only where their migration guides require it. The custom version-file plugin and the __APP_BUILD__ define must keep their current output.
FR-3: Lint toolchain¶
The system must move eslint to 10.x, @eslint/js to 10.x, eslint-plugin-react-hooks to 7.x, eslint-plugin-react-refresh to 0.5.x and globals to 17.x. eslint.config.js must be adapted to the new config exports (the current file spreads reactHooks.configs.recommended.rules). New rule violations follow Rule 6.
FR-4: Remove FontAwesome¶
The system must not declare any @fortawesome/* package.
FR-5: Node 22 in CI¶
.github/workflows/deploy-web.yml and .github/workflows/autopilot.yml must set node-version: '22' on their actions/setup-node steps that install webapp/.
FR-6: Documentation agrees with the code¶
.claude/rules/tech-strategy.mdand its mirrordocs/claude/rules/tech-strategy.md: Build Tool →Vite 8; HLS Playback →hls.js 1.7.4 (ADR-0031; …)README.mdstack table: Build Tool →Vite 8; Icons →Material Symbols Outlined(the README still names FontAwesome, which the code does not use)docs/tracking.mdrow updated when the work lands
FR-7: Commit body reports measurements¶
The commit message must list the new main-chunk gzip size, the hls chunk presence, the lint warning count and the npm audit counts after the upgrade.
API Changes¶
New Endpoints¶
N/A: no backend change.
Modified Endpoints¶
N/A: no backend change. The SPA keeps calling the same /v1/funny-app endpoints.
Database Changes¶
New Tables¶
N/A.
Modified Tables¶
N/A.
No Changes¶
No migration. api/ is untouched.
Security Requirements¶
Authentication¶
Unchanged: JWT handling in the SPA (webapp/src/api/) is not modified.
Authorization¶
Unchanged.
Data Validation¶
Unchanged.
Sensitive Data¶
No new data handling. Supply chain: only packages already declared (or their new majors) are installed; no new package is added. npm audit high/critical count must not increase versus the baseline of 12 (PRD NFR-4).
Caching Impact¶
No server cache impact (no Guava cache is touched).
Browser-side caching must keep working:
| Cache | Impact | Action |
|---|---|---|
Service worker (public/sw.js, copied to dist/sw.js) |
Caches hashed assets/* and the navigation shell |
Verify dist/sw.js is still emitted and assets keep content-hashed names |
version.json new-version check (src/pwa/useNewVersion.js) |
Compares /version.json with __APP_BUILD__ |
Verify dist/version.json is emitted with {"build": "<sha7>"} and useNewVersion.test.jsx passes |
| TanStack Query client cache | Library minor bump only | Covered by existing tests |
Frontend Changes¶
New Routes¶
None.
Modified Components¶
| Component | File | Change |
|---|---|---|
| Any component flagged by a new react-hooks 7 rule | webapp/src/** |
Local fix only, per Rule 6 |
| Build config | webapp/vite.config.js |
Only if Vite 8 / plugin-react 6 require it |
| Test config | webapp/vitest.config.js, webapp/src/test-setup.js |
Only if Vitest 5 / jsdom 29 / jest-dom 7 require it |
| Lint config | webapp/eslint.config.js |
Adapt to ESLint 10 and react-hooks 7 config exports |
| Manifest | webapp/package.json, webapp/package-lock.json |
New versions, FontAwesome removed, lockfile regenerated |
State Management¶
No new React Query keys or API calls.
Event / Job Changes¶
Domain Events¶
No change.
Scheduled Jobs¶
No AppScheduler change. CI workflows change only their Node version (FR-5).
Non-Functional Requirements¶
Performance¶
| Operation | Target |
|---|---|
| Main JS chunk gzip | ≤ 258.8 kB (baseline 246.44 kB + 5%) |
hls.js |
Still a separate chunk, loaded only through import('hls.js') in src/hooks/useHlsSource.js |
npm run build in CI |
Not slower than the previous green "Deploy Frontend" run on Node 20 |
Assumption: the size and time targets are guard rails (PRD NFR-1/2). A miss is investigated and reported in the commit body; it blocks only if the cause is an accidental change in chunking (e.g.
hls.jsmerged into the main chunk).
Availability¶
Static deploy, no downtime; rollback is a revert commit plus a redeploy.
Scalability¶
N/A.
Edge Cases¶
EC-1: Lockfile drift¶
Condition: npm install keeps old transitive versions from the existing lockfile.
Expected: regenerate the lockfile (rm -rf node_modules package-lock.json && npm install) after the version bumps, then confirm npm ci works from the new lockfile.
EC-2: Peer dependency conflict¶
Condition: npm install reports ERESOLVE (e.g. a plugin not yet declaring Vite 8 or ESLint 10 support).
Expected: stop and report the conflicting package. Do not use --force or --legacy-peer-deps to get past it; if no compatible release exists, that package stays one major behind and Rule 1 is recorded as not met in the commit body for owner decision.
EC-3: Rolldown changes chunk output¶
Condition: after the Vite 8 build, dist/assets/ has no separate hls-*.js, or version.json is missing.
Expected: treat as a blocker (behaviour change); fix the config so the chunk and file are emitted as before.
EC-4: New react-hooks rules flag code¶
Condition: npm run lint reports errors from rules that did not exist in react-hooks 5.
Expected: apply Rule 6 exactly (≤ 10 and local → fix; otherwise warn + TASKS.md follow-up per rule).
EC-5: Test fails only because of tooling semantics¶
Condition: a test fails due to a Vitest 5 / jsdom 29 / jest-dom 7 API or behaviour change, not an app bug. Expected: adapt the test to the new API keeping the same assertion (Rule 5). If an app bug is found, fix the app and keep the test.
EC-6: CI fails on Node 22 but local passes on Node 24¶
Expected: reproduce under Node 22 locally (nvm, or a node:22 Docker container running npm ci && npm run build) before changing code.
Acceptance Criteria¶
- [ ]
npm outdatedinwebapp/prints nothing (Rule 1) - [ ]
package.jsonhas no@fortawesome/*entry and"hls.js": "1.7.4"exactly (Rules 2, 3) - [ ]
npm cisucceeds from the committed lockfile (EC-1) - [ ]
npm run linthas 0 errors; any rule moved towarnhas aTASKS.mdfollow-up and noeslint-disablecomment was added (Rule 6) - [ ]
npx vitest run --root .passes 76 files and ≥ 655 tests (Rule 5) - [ ]
npm run buildsucceeds;dist/containsversion.json,sw.js,manifest.json, a separateassets/hls-*.js, and the main chunk is ≤ 258.8 kB gzip (FR-2, NFR) - [ ]
deploy-web.ymlandautopilot.ymluse Node 22 (Rule 8) - [ ] tech-strategy (both copies) and README name Vite 8 and hls.js 1.7.4; README icons row names Material Symbols (FR-6)
- [ ] Commit body lists chunk size, lint warnings and
npm auditcounts (FR-7) - [ ] "Deploy Frontend (React Build)" is green on the pushed commit
- [ ] Prod smoke passes: login, feed loads, HLS playback and Range fallback, admin pages, language switch, PWA new-version banner
- [ ]
mvn verifynot required (noapi/change)
Open Questions¶
None. Threshold for lint fallback resolved by owner on 2026-10-29 (Rule 6).
Version History¶
| Version | Date | Author | Change |
|---|---|---|---|
| 1.0 | 2026-10-29 | nguyenhuuca / Claude Code | Initial spec from PRD + ADR-0034 |