npm-package-updates

npm Package Updates

This skill guides you through the process of updating npm packages in this project, including minor/patch updates and major version updates.

Prerequisites

Check Environment

Determine if ddev is running:

ddev describe 2>/dev/null

• If the command succeeds (exit code 0), prefix every npm command with ddev gesso. Example: npm update --save becomes ddev gesso npm update --save
• If the command fails, run nvm use to ensure the correct Node version

Install packages

Run npm ci to ensure installed packages match package-lock.json

Part 1: Minor and Patch Version Updates

Minor and patch updates follow semantic versioning and should not introduce breaking changes.

Steps:

1. Update packages:

   npm update --save
   

   This updates packages to their latest minor and patch versions within the semver range specified in package.json.

2. Fix any issues:

   • Address any linting errors and warnings (stylelint, eslint)
   • Address any Sass deprecation warnings if relevant
   • Fix any formatting issues (prettier)
   • Resolve TypeScript errors if relevant
   • Update deprecated code patterns

3. Test the updates: Run all three test suites to ensure everything still works:

   npm run build            # Build application or theme
   npm run test             # Run linting and TypeScript checks
   npm run build-storybook  # Build Storybook
   

4. Commit the changes:

   git add package.json package-lock.json [other modified files]
   git commit -m "Minor and patch version updates"
   

Part 2: Major Version Updates

Major version updates may introduce breaking changes and require careful review.

Steps:

1. Identify packages with major updates:

   npm outdated
   

   Look for packages where the "Latest" version has a different major version than "Current".

2. Prioritize and filter updates:

   • Skip packages that have dedicated update branches
   • Skip Node.js version updates if not ready for that version
   • Prioritize dev dependencies over production dependencies
   • Start with smaller, less critical packages first

3. Research and summarize ALL major updates:

   For each package with a major update available:

   a. Research breaking changes:

   • Search for the package's changelog or release notes
   • Look for migration guides
   • Identify specific breaking changes between current and target version

   b. Check impact on codebase:

   • Search for package usage in the codebase
   • Review how the package is used
   • Verify if any breaking changes affect the current usage
   • Example checks:
     • Removed methods or properties
     • Changed API signatures
     • New required configurations
     • Removed or renamed options

   c. Document findings: Create a summary for each package including:

   • Package name and version change
   • List of breaking changes
   • Impact on codebase (specific files/code that need changes)
   • Whether it's blocked by issues or safe to proceed

4. Present summary to user and await decision:

   • Present all major update summaries in a clear format
   • Include source links for documentation
   • Ask the user which updates they want to proceed with
   • DO NOT proceed with any major updates until user explicitly approves

5. For each approved major update: c. Update the package:

   # For dev dependencies
   npm install <package-name>@latest --save-dev
   
   # For production dependencies
   npm install <package-name>@latest --save
   

   d. Test the update: Run the full test suite:

   npm run build
   npm run test
   npm run build-storybook
   

   d. Handle failures:

   • If tests fail, review the error messages
   • Check if additional code changes are needed
   • Rerun tests after fixes
   • If unable to resolve, roll back and inform user

   e. Commit the update:

   git add package.json package-lock.json [other modified files]
   git commit -m "Update <package-name> to v<version>"
   

Testing Requirements

All updates must pass these tests before committing:

1. Next.js Build (npm run build)

   • Compiles successfully
   • No build errors
   • Linting passes
   • Type checking passes

2. Test Suite (npm run test)

   • ESLint: No warnings or errors
   • Stylelint: No CSS linting errors
   • TypeScript: No type errors

3. Storybook Build (npm run build-storybook)

   • Builds successfully
   • All stories compile

Commit Message Format

• Minor/patch updates: "Minor and patch version updates"
• Major updates: "Update <package-name> to v<version>"
• Include only the changes relevant to that commit

Example: Major Update Workflow

For updating @inquirer/prompts from v7 to v8:

1. Check npm outdated → Found v8.0.1 available
2. Research breaking changes → Found 5 breaking changes
3. Check codebase usage → Used in lib/create-component.mjs
4. Verify no impact → None of the breaking changes affect our usage
5. Update: npm install @inquirer/prompts@latest --save-dev
6. Test: Run build, test, build-storybook
7. Commit: "Update @inquirer/prompts to v8.0.1"

Notes

• Always test thoroughly before committing
• Pre-commit hooks will automatically run tests
• If pre-commit modifies files, verify changes and amend if safe
• Keep commits focused on specific updates for easier review and rollback
• Document any code changes required by updates in commit messages if significant