Get the FREE Ultimate OpenClaw Setup Guide →

node-upgrade

Scanned
npx machina-cli add skill yu-iskw/coding-agent-fabric/node-upgrade --openclaw
Files (1)
SKILL.md
2.6 KB

Safe Node.js Dependency Upgrade

This skill provides a structured process for safely upgrading Node.js dependencies, ensuring project stability through pre-upgrade health checks and post-upgrade validation.

1. Preparation & Health Check

Before making any changes, verify the current state of the project:

  1. Baseline Health Check:
    • Run an audit: pnpm audit.
    • Run the test suite: pnpm test.
    • Constraint: If the baseline tests fail, resolve those issues before proceeding with upgrades.
  2. Backup:
    • Backup package.json and the lockfile: cp pnpm-lock.yaml pnpm-lock.yaml.bak.

2. Upgrade Execution

Choose the appropriate upgrade path based on the user's request. Refer to ../common-references/pnpm-commands.md for pnpm-specific commands.

Targeted Upgrade (Recommended)

Use this when the user specifies a package or a small set of packages.

  1. Upgrade: Run the targeted upgrade command (e.g., pnpm update <package>).
  2. Verify: Check package.json to ensure the version has been updated.

Full Upgrade (Maintenance)

Use this for general dependency maintenance.

  1. Upgrade: Run the full upgrade command (e.g., pnpm update).
  2. Check for Breaking Changes: Review the lockfile changes and check for major version bumps.

3. Validation & Verification

After the upgrade, ensure the project remains stable by delegating to the project verifier:

  1. Invoke Verifier: Use the verifier subagent (../../agents/verifier.md) to run the full build, lint, and test cycle.
  2. Handle Failure: If the verifier reports persistent issues it cannot fix, analyze the breaking changes and apply manual fixes or roll back.
  3. Final Audit: Once the verifier passes, run pnpm audit again to ensure no new vulnerabilities were introduced.

4. Finalization

  1. Commit: Create a commit with the updated package.json and lockfile.
    • Message Suggestion: chore(deps): upgrade dependencies
  2. Cleanup: Remove backup files: rm *.bak.

Rollback Plan

If validation fails and cannot be easily fixed:

  1. Restore: mv package.json.bak package.json and mv <lockfile>.bak <lockfile>.
  2. Re-install: Run pnpm install to restore the environment.
  3. Report: Notify the user of the failure and the reasons (e.g., specific breaking changes).

Source

git clone https://github.com/yu-iskw/coding-agent-fabric/blob/main/.claude/skills/node-upgrade/SKILL.mdView on GitHub

Overview

Safely upgrade Node.js dependencies in pnpm workspaces with a structured, low-risk workflow. It emphasizes baseline health checks, a backup of package.json and the lockfile, and post-upgrade validation via a verifier. This approach helps prevent breaking changes and makes rollbacks straightforward if issues arise.

How This Skill Works

Begin with a baseline health check using pnpm audit and pnpm test, then back up package.json and pnpm-lock.yaml. Depending on the request, perform a targeted upgrade (pnpm update <package>) or a full upgrade (pnpm update), then validate with the verifier and run a final pnpm audit before committing changes.

When to Use It

  • When asked to upgrade dependencies
  • When updating packages
  • When checking for updates
  • When fixing version mismatches across workspaces
  • Before a major project release or maintenance window

Quick Start

  1. Step 1: Run baseline health checks (pnpm audit; pnpm test)
  2. Step 2: Back up package.json and pnpm-lock.yaml (cp pnpm-lock.yaml pnpm-lock.yaml.bak)
  3. Step 3: Choose upgrade path (pnpm update <package> or pnpm update) and run, then use the verifier and final audit before committing

Best Practices

  • Always run baseline health checks (pnpm audit and pnpm test) before upgrading
  • Back up package.json and pnpm-lock.yaml prior to making changes
  • Prefer targeted upgrades for small sets of packages when possible
  • Review lockfile changes for breaking changes and major version bumps
  • Use the verifier for a full build, lint, and test cycle and keep a rollback plan ready

Example Use Cases

  • Upgrade a single package, e.g., pnpm update react-dom, and verify package.json reflects the new version
  • Perform a full upgrade (pnpm update) across the workspace as part of maintenance
  • Resolve a version mismatch across workspaces by upgrading the conflicting package to a compatible version
  • If the verifier reports issues, analyze breaking changes and apply fixes or rollback
  • Run pnpm audit before and after upgrades to ensure no new vulnerabilities are introduced

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗