upgrade-frontend-deps
Skill67 starsChanged 16 days agoMITView on GitHub
Upgrade the Next.js frontend's pnpm dependencies to their latest versions in verified waves. Inventories with `pnpm outdated`, removes verified-unused deps, batches safe minor/patch bumps, handles the @langchain/react + langgraph-sdk lockstep pair, takes majors one commit at a time with registry peer-dep checks, gates every wave on type-check + lint + unit tests + build + an agent-browser check against baseline screenshots, then dedupes, audits for duplicate versions, and opens a PR. Use when the user says "upgrade frontend libs", "bump frontend deps", "update npm/pnpm packages", or `pnpm outdated` shows a backlog. Backend deps are a separate flow (`upgrade-backend-deps`).
- Deletes or force-pushes
- Installs packages
- Commits and pushes
In this repository23 other files it gives its agents.
- AGENTS.mdAGENTS.md
- analytics/AGENTS.mdAGENTS.md
- backend/AGENTS.mdAGENTS.md
- frontend/AGENTS.mdAGENTS.md
- agent-browserSkill
- archify-reviewSkill
- archifySkill
- commitSkill
- drawio-skillSkill
- frontend-designSkill
- qualitySkill
- upgrade-backend-depsSkill
- write-prdSkill
- agent-browserSkill
- archify-reviewSkill
- archifySkill
- commitSkill
- drawio-skillSkill
- frontend-designSkill
- qualitySkill
- upgrade-backend-depsSkill
- upgrade-frontend-depsSkill
- write-prdSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 70
If any dep looks unused, verify empirically (grep imports across src/ AND config files — a dep can be config-only like a tailwind plugin), …
- Very specific: line 84
Follow the protocol in frontend/AGENTS.md exactly: bump @langchain/react first, read its pinned SDK version (pnpm view …
- Distinctive: line 122
Run the full E2E one last time on the final state, then commit the dedupe diff if any.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Upgrade the frontend's pnpm dependencies in revertable waves, preserving exact-pin style and the single-resolved-version invariant, with browser verification against a pre-upgrade baseline.
Ground rules
- Exact pins stay exact.
react,react-dom, and@langchain/langgraph-sdkhave no^inpackage.json. Upgrade them withpnpm --dir frontend add -E pkg@x.y.z; everything else gets a new^floor (pnpm --dir frontend add pkg@^x.y.z). - A held-back line needs a
~range.^x.y.zadmits every later minor, and pnpm resolves the highest match —pnpm add better-auth@^1.6.30installed 1.7.2, the version being held back. When a package must stay on its current minor (schema migration, peer gate), pin~x.y.z; when even a later patch is the problem, pin it exactly (-E). Say so under "Held back", and restore^in the PR that lifts the hold (pnpm keeps an exact pin exact on the nextadd, so edit the range by hand and re-runpnpm install). Always read the+ pkg x.y.zline pnpm prints afteradd— it is the installed version, not the range you typed. - One resolved version per dep. The lockfile must not carry two copies of anything that crosses a package boundary (the
@langchain/langgraph-sdksingle-copy invariant infrontend/AGENTS.mdis the critical one;scripts/check-langchain-sdk-sync.mjsguards it). - One commit per wave (majors: one per package) so any regression reverts surgically.
- Lockfile changes need
docker compose restart frontend; source edits hot-reload. Never restart for source-only changes; never skip the restart afterpnpm add/remove. @types/nodetracks the Docker runtime, not npmlatest. Read the major fromfrontend/Dockerfile'sFROM node:XX-alpineand stay on@types/node@^XX. Document it under "Held back".vitest+@vitest/coverage-v8are an exact-version lockstep pair (coverage is an exact peer of the runner) — bump both together in one command; a split pair breakspnpm test:coverage. Since vitest 5,viteis a required peer rather than a dependency: keep it as an explicit devDependency (vite@^8) so the resolved version is declared, not left to pnpm's auto-installed peers.
Workflow
1. Inventory
pnpm --dir frontend outdated --format jsonExits 1 when anything is outdated — that's data, not an error. Split the list into: patch/minor (wave 3), majors (waves 5–7), and the LangChain pair (wave 4). For every major, check compatibility before planning:
pnpm view "pkg@<target>" peerDependencies # quote the spec; zsh doesn't word-split varsGate examples that have mattered: typescript-eslint's typescript: <X upper bound gates TS majors; eslint plugins' eslint peer range gates eslint majors. A major whose peers don't fit gets held back, not forced.
Read release notes for the auth/database libraries even below a major, patches included: better-auth 1.7.0 (a minor) added a NOT NULL account.issuer column with a required backfill, and 1.7.3 (a patch) reverted it — databases that ran 1.7.0–1.7.2 must relax that column before 1.7.3+ can sign anyone up (README, frontend/scripts/better-auth-1.7.3-relax-account-issuer.sql). A schema migration is not a wave; hold the package (~ range, or an exact pin when the problem is a patch) and leave the bump to its own PR that also updates the README migration steps. Verify such a bump with the pinned CLI's read-only auth check schema.
2. Branch + baseline
git switch -c chore/upgrade-frontend-deps
cd frontend && pnpm install --frozen-lockfile # host node_modules current (pre-commit hooks need it)
pnpm type-check && pnpm lint && pnpm test && pnpm build # "Gate G" — must be green BEFORE touching anythingRecord the current lint warning count — you'll need to distinguish pre-existing warnings from upgrade fallout later.
Then capture a browser baseline with agent-browser (agent-browser skills get core for the workflow):
- Screenshots, light AND dark (
agent-browser set media dark|light): home, a thread with markdown + code blocks, the file dialog open, the select dropdown open,/print/file. - One full E2E run: send a real job-prep prompt, wait for completion, confirm streaming, subagent cards, plan progress, and workspace artifacts. To submit a multiline prompt (Enter sends in this UI), set the textarea via the React native-setter instead of typing:
cat <<'EOF' | agent-browser eval --stdin
{
const el = document.querySelector('textarea');
const set = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value').set;
set.call(el, `multi
line
prompt`);
el.dispatchEvent(new Event('input', { bubbles: true }));
}
EOF
agent-browser find role button click --name "Send"- Completion signal: poll until
agent-browser snapshot -i -cno longer showsbutton "Stop"(background loop, ~30s interval, run-in-background so you're notified). /print/filereads a JSON payload fromsessionStorage["nextrole:print-file"]— set a fixed synthetic markdown payload (heading, list, blockquote, fenced code, table) and reuse the same payload post-upgrade for an apples-to-apples diff.
3. Wave: removals, then minor/patch batch
If any dep looks unused, verify empirically (grep imports across src/ AND config files — a dep can be config-only like a tailwind plugin), confirm with the user if it wasn't already agreed, remove, and commit separately.
Then bump all patch/minors in one command with the new versions as explicit floors, exact pins via -E:
pnpm --dir frontend add pkgA@^x.y.z pkgB@^x.y.z ...
pnpm --dir frontend add -E react@x.y.z react-dom@x.y.z
pnpm --dir frontend add -D devPkg@^x.y.z ...Gate G + restart + a quick browser smoke (page loads, open an existing thread). Commit.
4. Wave: @langchain/react + langgraph-sdk lockstep
Follow the protocol in frontend/AGENTS.md exactly: bump @langchain/react first, read its pinned SDK version (pnpm view "@langchain/react@<ver>" dependencies), then pnpm --dir frontend add -E @langchain/langgraph-sdk@<that-version>, then:
pnpm --dir frontend run check:sdk-sync # must print "single copy"This wave touches the streaming layer — run the full E2E (not just a smoke): streaming tokens, subagent cards populating live, then reload the idle thread and submit again (catches replay/resume regressions). Commit.
5. Wave: independent majors, one commit each, cheapest first
For each major: read the changelog/release notes, but treat the installed package's .d.ts as ground truth for API shape — and verify semantics empirically when the types are ambiguous. Real example: react-resizable-panels v4's d.ts doesn't say bare numeric sizes became pixels (v3: percent); only a browser check caught panels collapsing to 30px. Research can be wrong in both directions — a claim that "numbers still mean %" survived two reviews here.
Per package: pnpm add, make any source edits, Gate G, targeted browser check of the surfaces that package owns (markdown → chat bubbles + dialogs; highlighter → code blocks light/dark; icons → render pass; panels → drag, reload-persistence, sidebar toggle, console clean), commit. One restart at wave end is fine if no package needed an interactive check earlier.
6. Wave: toolchain (eslint / typescript)
Dev-only but loud. Expect new findings, not breakage: new eslint core rules and react-hooks compiler rules flag pre-existing patterns. Policy: fix trivial ones; downgrade noisy new rules to "warn" in eslint.config.js with a comment — do not refactor app logic inside a deps PR. For TS majors, check tsconfig fallout (TS 6 dropped auto-inclusion of node_modules/@types → needed "types": ["node"]). Gate G, commit.
7. Wave: coupled/risky majors last (own commits = revert lever)
Anything that rewires a build pipeline (CSS framework, bundler plugin) goes last, in two commits: codemod output, then manual fixes. Two lessons that generalize:
- A green build does not mean correct output. After pipeline changes, grep the emitted artifact for invariants, e.g. compiled CSS must contain the expected utility rules. Minified CSS gotchas:
grep -ccounts lines (minified = 1 line — usegrep -o | wc -l), minifiers merge selectors (.a,.b{...}— don't anchor on.cls{), and attribute quotes get stripped ([type=checkbox], not[type='checkbox']). - "Now it finally works" can be a regression. Classes/config that were silently dead under the old version (never emitted CSS) may come alive after the upgrade and change rendering. The pre-upgrade baseline screenshots are the arbiter — match the baseline, not the docs' idea of correct. Tailwind-4-specific landmines for this repo are recorded in
tailwind.config.mjs/globals.csscomments and the PR #16 description (prose is an intentional no-op; element CSS stays in@layer base; packaged plugins load via@pluginlines, not the@configplugins array).
Full visual checklist vs baseline (light + dark, dialogs, selects, hover, print page), plus a cold-build check: rm -rf frontend/.next && pnpm --dir frontend build and grep the emitted CSS.
8. Finalize
pnpm --dir frontend dedupe
pnpm --dir frontend run check:sdk-sync # dedupe must not split the SDK copy
pnpm --dir frontend outdated # expect: empty, or only documented hold-backs
cd frontend && pnpm quality && pnpm test && pnpm build
docker compose restart frontend
pnpm --dir frontend why clsx react react-dom @langchain/langgraph-sdk # one version eachRun the full E2E one last time on the final state, then commit the dedupe diff if any.
9. PR
Push using gh or git push (already uses the right SSH identity), open the PR with mcp__github__create_pull_request (owner tam159, repo next-role, base main). Body follows the PR #15/#16 format: Summary / Upgraded table (old → new, mark exact pins) / Removed / Held back (with reasons) / Migration notes / Test plan. Watch code-quality + backend-tests; fix failures in the same PR. Leave merging to the user.
10. Report
- Upgraded: direct deps with old → new (the wave commits are the ledger).
- Removed: with the verification evidence (zero imports / config-only / dead config).
- Held back: package, available version, and the concrete blocker (peer range, runtime match, failed gate + revert).
- Surprises that cost time — they're the seed of the next AGENTS.md/skill update.
Gotchas
pnpm outdatedexits 1 when outdated packages exist — don't treat as failure.- Pre-commit reformats, then fails the commit. prettier (+ class sorting) rewrites codemod/sed output on first commit attempt → "files were modified by this hook". Re-stage and commit again; second pass is clean. After any hook auto-fix, re-read files before further edits.
- Browser console/errors accumulate across container restarts. A scary
CssSyntaxErroror missing-module error may be from the window when the container was mid-restart with mismatched node_modules.agent-browser errors --clear+ reload before judging; only fresh-after-reload errors are real. - agent-browser refs go stale on re-render — re-snapshot before clicking;
scrollintoviewbefore clicking elements outside the viewport (clicks can silently no-op). - Screenshots save relative to the daemon's cwd, not the shell's — always pass absolute paths (
agent-browser screenshot /tmp/...png), or strays land in the repo. - pnpm 10 blocks postinstall scripts of new deps (e.g.
@tailwindcss/oxide). If pnpm warns "Ignored build scripts", allowlist viapnpm.onlyBuiltDependenciesand reinstall. - The E2E creates real threads/files in the dev stack — they overwrite by deterministic path on re-runs; leave or bulk-delete at the end, but say which.
- The E2E depends on the model provider, and a provider failure looks like a frontend bug. When the backend's model call dies (Azure OpenAI "peak load" / 5xx), the run ends with an empty assistant turn and no toast. Check
docker compose logs backendforBackground run failedbefore suspecting the upgrade. Unblock by setting the demo user's Main agent and Subagents fields in Settings to a healthyprovider:model(e.g.anthropic:claude-sonnet-5); it is a per-browser preference, so the owner's config is untouched.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

