You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
177 lines
4.7 KiB
177 lines
4.7 KiB
# Dependency Management — Best Practices
|
|
|
|
> **Agent role**: Reference this file for dependency management strategies and
|
|
best practices when working with software projects.
|
|
|
|
## Dependency Management Best Practices
|
|
|
|
### Pre-build Validation
|
|
|
|
- **Check Critical Dependencies**:
|
|
|
|
Validate essential tools before executing build
|
|
scripts
|
|
|
|
- **Use npx for Local Dependencies**: Prefer `npx tsx` over direct `tsx` to
|
|
|
|
avoid PATH issues
|
|
|
|
- **Environment Consistency**: Ensure all team members have identical dependency
|
|
|
|
versions
|
|
|
|
### Common Pitfalls
|
|
|
|
- **Missing npm install**: Team members cloning without running `npm install`
|
|
|
|
- **PATH Issues**: Direct command execution vs. npm script execution differences
|
|
|
|
- **Version Mismatches**: Different Node.js/npm versions across team members
|
|
|
|
### Validation Strategies
|
|
|
|
- **Dependency Check Scripts**: Implement pre-build validation for critical
|
|
|
|
dependencies
|
|
|
|
- **Environment Requirements**:
|
|
|
|
Document and enforce minimum Node.js/npm versions
|
|
|
|
- **Onboarding Checklist**: Standardize team member setup procedures
|
|
|
|
### Error Messages and Guidance
|
|
|
|
- **Specific Error Context**:
|
|
|
|
Provide clear guidance when dependency issues occur
|
|
|
|
- **Actionable Solutions**: Direct users to specific commands (`npm install`,
|
|
|
|
`npm run check:dependencies`)
|
|
|
|
- **Environment Diagnostics**: Implement comprehensive environment validation
|
|
|
|
tools
|
|
|
|
### Build Script Enhancements
|
|
|
|
- **Early Validation**: Check dependencies before starting build processes
|
|
|
|
- **Graceful Degradation**: Continue builds when possible but warn about issues
|
|
|
|
- **Helpful Tips**: Remind users about dependency management best practices
|
|
|
|
## Environment Setup Guidelines
|
|
|
|
### Required Tools
|
|
|
|
- **Node.js**: Minimum version requirements and LTS recommendations
|
|
|
|
- **npm**: Version compatibility and global package management
|
|
|
|
- **Platform-specific tools**: Android SDK, Xcode, etc.
|
|
|
|
### Environment Variables
|
|
|
|
- **NODE_ENV**: Development, testing, production environments
|
|
|
|
- **PATH**: Ensure tools are accessible from command line
|
|
|
|
- **Platform-specific**: Android SDK paths, Xcode command line tools
|
|
|
|
### Validation Commands
|
|
|
|
```bash
|
|
|
|
# Check Node.js version
|
|
|
|
node --version
|
|
|
|
# Check npm version
|
|
|
|
npm --version
|
|
|
|
# Check global packages
|
|
|
|
npm list -g --depth=0
|
|
|
|
# Validate platform tools
|
|
|
|
npx capacitor doctor
|
|
|
|
```
|
|
|
|
## Dependency Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Permission Errors**: Use `sudo` sparingly, prefer `npm config set prefix`
|
|
|
|
2. **Version Conflicts**: Use `npm ls` to identify dependency conflicts
|
|
|
|
3. **Cache Issues**: Clear npm cache with `npm cache clean --force`
|
|
|
|
4. **Lock File Issues**: Delete `package-lock.json` and `node_modules`,
|
|
|
|
then reinstall
|
|
|
|
### Resolution Strategies
|
|
|
|
- **Dependency Audit**: Run `npm audit` to identify security issues
|
|
|
|
- **Version Pinning**: Use exact versions for critical dependencies
|
|
|
|
- **Peer Dependency Management**: Ensure compatible versions across packages
|
|
|
|
- **Platform-specific Dependencies**: Handle different requirements per platform
|
|
|
|
## Best Practices for Teams
|
|
|
|
### Onboarding
|
|
|
|
- **Environment Setup Script**: Automated setup for new team members
|
|
|
|
- **Version Locking**: Use `package-lock.json` and `yarn.lock` consistently
|
|
|
|
- **Documentation**: Clear setup instructions with troubleshooting steps
|
|
|
|
### Maintenance
|
|
|
|
- **Regular Updates**: Schedule dependency updates and security patches
|
|
|
|
- **Testing**: Validate changes don't break existing functionality
|
|
|
|
- **Rollback Plan**: Maintain ability to revert to previous working versions
|
|
|
|
**See also**:
|
|
`.cursor/rules/development/software_development.mdc` for core development principles.
|
|
|
|
**Status**: Active dependency management guidelines
|
|
**Priority**: Medium
|
|
**Estimated Effort**: Ongoing reference
|
|
**Dependencies**: software_development.mdc
|
|
**Stakeholders**: Development team, DevOps team
|
|
|
|
## Model Implementation Checklist
|
|
|
|
### Before Dependency Changes
|
|
|
|
- [ ] **Current State Review**: Check current dependency versions and status
|
|
- [ ] **Impact Analysis**: Assess impact of dependency changes on codebase
|
|
- [ ] **Compatibility Check**: Verify compatibility with existing code
|
|
- [ ] **Security Review**: Review security implications of dependency changes
|
|
|
|
### During Dependency Management
|
|
|
|
- [ ] **Version Selection**: Choose appropriate dependency versions
|
|
- [ ] **Testing**: Test with new dependency versions
|
|
- [ ] **Documentation**: Update dependency documentation
|
|
- [ ] **Team Communication**: Communicate changes to team members
|
|
|
|
### After Dependency Changes
|
|
|
|
- [ ] **Comprehensive Testing**: Test all functionality with new dependencies
|
|
- [ ] **Documentation Update**: Update all relevant documentation
|
|
- [ ] **Deployment Planning**: Plan and execute deployment strategy
|
|
- [ ] **Monitoring**: Monitor for issues after deployment
|
|
|