# Stack Modernization

> Modernize a project's stack — outdated dependencies, dead/unused packages, deprecated packages, and framework-pattern drift (old patterns lingering after a major upgrade). Verifies the current latest of each package before proposing an upgrade, then applies changes incrementally with tests between each. Use when asked to update dependencies, modernize the stack, remove dead packages, or migrate stale framework patterns, across frontend and backend.

- Skill: `shipshitdev/stack-modernization` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add shipshitdev/stack-modernization`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shipshitdev/stack-modernization/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: shipshitdev (https://skillmd.com/u/shipshitdev)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/shipshitdev/stack-modernization

---


# Stack Modernization

Keep a project on current, minimal, idiomatic dependencies. Three jobs: upgrade what
is behind, delete what is unused, and migrate patterns a major upgrade left stranded
(the v3 config still sitting in a v4 repo). Edits `package.json` and source, so it
runs behind a confirmation gate and verifies before it upgrades.

Never trust training data for a version number — the current latest is looked up, not
recalled.

## Authorized Scope

Apply this engine only within the user's requested task and existing explicit
authorization. Loading or delegating to it grants no additional authority.
Preserve report-only restrictions and the caller's target, host, provider, and
cost limits. Existing approval satisfies a gate only for the same actions and
scope; obtain approval before expanding them. Forward these limits to delegates.

## Contract

Inputs:

- A repo; optional focus (`deps` / `dead` / `patterns` / `all`, default `all`).

Outputs:

- A modernization plan (per package: current → latest, risk, migration notes), then
  applied upgrades with tests passing between steps.

Creates/Modifies:

- Edits `package.json`, lockfile, and source during pattern migration. Only after the
  plan is approved.

External Side Effects:

- `bun` install/upgrade commands; `WebSearch` to confirm latest versions. No deploys.

Confirmation Required:

- Before applying any upgrade or removal. Show the plan first.
- Before a major-version bump with a migration cost — call it out explicitly.

Delegates To:

- `refactor-code` when a migration is a real code refactor, not a mechanical swap.
- `dependency-audit` for the security/CVE angle (this skill is about currency, that
  one about vulnerability).

## Step 1 — Inventory

```bash
bun outdated                 # what is behind, and by how much (patch / minor / major)
bun pm ls                    # installed tree
# Dead/unused packages: run knip or depcheck if present; else grep imports per dep.
```

Also flag **framework-pattern drift** — a stale lockfile or config alongside a newer
major:

- `npm`/`yarn`/`pnpm` lockfiles or install commands in a Bun project.
- A `tailwind.config.{js,ts}` or `@apply`/`@tailwind` directives in a Tailwind v4
  project (v4 configures in the CSS `@theme` block).
- `middleware.ts` where the framework's current major expects `proxy.ts`.
- Deprecated APIs the installed major has replaced (check the package's migration guide).

## Step 2 — Verify latest before proposing

For each candidate upgrade, confirm the **current** latest with `WebSearch` (npm/GitHub
releases) — do not use a version from memory. Note the target major and whether the
package publishes a breaking-change / migration guide.

## Step 3 — Plan

```markdown
## Stack Modernization Plan — <repo>

### Upgrade
| Package | Current | Latest | Jump | Migration |
|---------|---------|--------|------|-----------|
| <name>  | x.y.z   | a.b.c  | major/minor/patch | <link or "none"> |

### Remove (unused)
- <package> — no imports found

### Pattern migration
- <stale pattern> → <current pattern>
```

Order the work: security/patch and minor upgrades first (low risk), then majors with
migrations one at a time, then dead-package removal, then pattern migration.

## Step 4 — Apply incrementally

One change at a time; tests between each so a regression is attributable:

```bash
bun add <pkg>@<verified-latest>     # or `bun remove <pkg>` for dead deps
bun run type-check || bunx tsc --noEmit
bun run test <affected-area>
```

Commit each successful step so any failure rolls back cleanly. For a major with a
migration guide, follow it explicitly rather than guessing the new API.

## Anti-Patterns

- **Upgrading to a version from memory.** Always verify the current latest first —
  training data is stale for version numbers.
- **A big-bang upgrade of everything at once.** One package (or one coherent group) at
  a time, tests between, so a break is traceable.
- **Bumping a major without reading its migration guide** — the breaking changes are
  the whole point of the major.
- **Removing a package on a missing import alone** — check for dynamic imports, config
  references, and peer-dependency roles before deleting.
- **Reintroducing npm/yarn** — this project uses Bun; upgrades go through `bun add`.