04_dependency_management

Dependency Management

Managing external dependencies is a critical part of modern web development. This document outlines our best practices for adding, updating, and removing dependencies.

Adding a New Dependency

Before adding a new dependency, ask yourself:

1. Is this dependency necessary? Can we achieve the same functionality with our existing tools or with a small amount of custom code?
2. Is this dependency well-maintained? Check the package on npm/GitHub.
   • Does it have a healthy number of downloads?
   • When was it last updated?
   • Are there many open issues?
3. Is it secure? Are there any known vulnerabilities associated with it?
4. What is its bundle size? How will this impact our application’s performance? Use a tool like BundlePhobia to check.

If you decide to add the dependency, follow these steps:

1. Discuss with the team: For significant dependencies (e.g., a new state management library, a UI component library), discuss it with the team first.
2. Use npm or yarn: Add the dependency using the project’s package manager.
   • npm install [package-name]
   • npm install --save-dev [package-name] (for development dependencies)
3. Commit the package-lock.json file: This file is crucial for ensuring that all developers and the CI/CD environment use the exact same versions of all dependencies.

Updating Dependencies

• Regular Updates: Dependencies should be updated regularly to get the latest features, bug fixes, and security patches.
• Use npm outdated: This command will show you which dependencies are out of date.
• Semantic Versioning: Understand what the version numbers mean:
  • MAJOR (e.g., 2.x.x → 3.x.x): Contains breaking changes. These updates require careful testing.
  • MINOR (e.g., 2.1.x → 2.2.x): Contains new features, but should be backward-compatible.
  • PATCH (e.g., 2.1.1 → 2.1.2): Contains bug fixes and should be safe to update.
• Update Process:
  1. Run npm update to install the latest patch and minor versions.
  2. For major version updates, update each package individually and test thoroughly.
  3. Run the full test suite after updating to ensure nothing has broken.

Security Scanning

• Automated Scanning: We use automated tools like npm audit and GitHub’s Dependabot to continuously scan for vulnerabilities in our dependencies. Our full process for this is detailed in the Dependency Scanning SOP.
• npm audit:
  • Run npm audit regularly to check for known vulnerabilities.
  • Run npm audit fix to automatically fix compatible vulnerabilities. For breaking changes, you may need to manually update the package.
• Dependabot: GitHub’s Dependabot will automatically create Pull Requests to update dependencies with known security vulnerabilities. These PRs should be reviewed and merged promptly.

Removing Dependencies

• If a dependency is no longer used, remove it from the package.json file to keep the project clean and reduce bundle size.
• npm uninstall [package-name]