Managing Updates

This guide covers two primary aspects of update management: Node.js version updates and npm dependency management.

Node.js Version Management

The stack runs on the current active LTS version of Node.js. You can update the Node.js version in two places:

Package.json Configuration

Update the engines.node property:

{
  "engines": {
    "node": "20.3.1"
  }
}

Important: Use exact versions, not ranges, as this affects server compilation.

Dockerfile Update

Match the Node.js version in your Dockerfile:

FROM node:20.3.1-bookworm-slim as base

Find available versions on Docker Hub.

Template Code Management

When starting a new project, you receive a complete codebase that you own. This means:

• Full control over the code
• Freedom to customize
• Manual update management
• Project-specific modifications

Update the code based on your needs rather than feeling compelled to stay current with every change in the template.

NPM Dependency Updates

Using npm-check-updates

NPM Check Updates helps manage dependency updates safely:

# Check available updates
npx npm-check-updates

Understanding Update Types

Updates are color-coded by type:

• 🟢 Green: Patch updates (backward-compatible fixes)
• 🔵 Cyan: Minor updates (new features)
• 🔴 Red: Major updates (breaking changes)

Update Strategy

1. Patch Updates (Green)

# Update all patch versions
npx npm-check-updates -u --target patch
npm install

Run tests:

npm run test -- run
npm run test:e2e:run

Commit changes:

git add .
git commit -m "chore: update patch dependencies"

2. Minor Updates (Cyan)

Update individually:

npx npm-check-updates -u --filter <package-name>
npm install

Review:

• Release notes
• New features
• Necessary code updates

Run tests and commit:

npm run test -- run
npm run test:e2e:run
git add .
git commit -m "feat: update minor dependency versions"

3. Major Updates (Red)

Handle with care:

npx npm-check-updates -u -f <package-name>
npm install

Before updating:

• Read release notes
• Plan migration
• Test thoroughly
• Update application code

Best Practices

Version Control

1. Separate commits for different update types
2. Clear commit messages
3. Document breaking changes
4. Tag major updates

Testing

1. Run full test suite
2. Check for deprecation warnings
3. Verify all features work
4. Test in staging environment

Documentation

1. Update internal docs
2. Note breaking changes
3. Update configuration examples
4. Update deployment guides

Monitoring

1. Watch for deprecation notices
2. Monitor security advisories
3. Keep track of LTS schedules
4. Review update impact

Troubleshooting

Common Issues

1. Version conflicts
2. Breaking changes
3. Deprecated features
4. Integration failures

Resolution Steps

1. Check error logs
2. Review package documentation
3. Test in isolation
4. Roll back if necessary

For deployment-related updates, see the deployment documentation. For testing strategies, refer to the testing documentation.