eff7e339af
- Remove legacy rule files (documentation.mdc, general_development.mdc, etc.) - Implement new meta-rule system with core, app, and feature categories - Add meta-rule files for different workflows (bug diagnosis, feature planning, etc.) - Create organized directory structure: core/, app/, features/, database/, etc. - Add comprehensive README.md for rules documentation - Establish new rule architecture with always-on and workflow-specific rules This restructuring improves rule organization, enables better workflow management, and provides clearer separation of concerns for different development tasks.
178 lines
4.7 KiB
Plaintext
178 lines
4.7 KiB
Plaintext
# 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
|