# 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