agentleFS
tam159tam159/next-role/.claude/skills/upgrade-frontend-deps/SKILL.md

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

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
  1. Very specific:

    If any dep looks unused, verify empirically (grep imports across src/ AND config files — a dep can be config-only like a tailwind plugin), …

    line 70
  2. Very specific:

    Follow the protocol in frontend/AGENTS.md exactly: bump @langchain/react first, read its pinned SDK version (pnpm view …

    line 84
  3. Distinctive:

    Run the full E2E one last time on the final state, then commit the dedupe diff if any.

    line 122

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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-sdk have no ^ in package.json. Upgrade them with pnpm --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.z admits every later minor, and pnpm resolves the highest match — pnpm add better-auth@^1.6.30 installed 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 next add, so edit the range by hand and re-run pnpm install). Always read the + pkg x.y.z line pnpm prints after add — 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-sdk single-copy invariant in frontend/AGENTS.md is the critical one; scripts/check-langchain-sdk-sync.mjs guards 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 after pnpm add/remove.
  • @types/node tracks the Docker runtime, not npm latest. Read the major from frontend/Dockerfile's FROM node:XX-alpine and stay on @types/node@^XX. Document it under "Held back".
  • vitest + @vitest/coverage-v8 are an exact-version lockstep pair (coverage is an exact peer of the runner) — bump both together in one command; a split pair breaks pnpm test:coverage. Since vitest 5, vite is 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 json

Exits 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 vars

Gate 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 anything

Record 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 -c no longer shows button "Stop" (background loop, ~30s interval, run-in-background so you're notified).
  • /print/file reads a JSON payload from sessionStorage["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 -c counts lines (minified = 1 line — use grep -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.css comments and the PR #16 description (prose is an intentional no-op; element CSS stays in @layer base; packaged plugins load via @plugin lines, not the @config plugins 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 each

Run 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 outdated exits 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 CssSyntaxError or 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; scrollintoview before 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 via pnpm.onlyBuiltDependencies and 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 backend for Background run failed before suspecting the upgrade. Unblock by setting the demo user's Main agent and Subagents fields in Settings to a healthy provider:model (e.g. anthropic:claude-sonnet-5); it is a per-browser preference, so the owner's config is untouched.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.