0
# Project Updates
1

2
Update functionality for existing jslib projects, allowing seamless upgrades to the latest template version and tooling configuration.
3

4
## Capabilities
5

6
### Update Command
7

8
Updates an existing jslib project to the latest CLI version and template configuration.
9

10
```bash { .api }
11
jslib update
12
jslib u
13

14
# Requirements:
15
# - Must be run in project root directory
16
# - Directory must contain jslib.json configuration file
17
# - Project must have been created with @js-lib/cli
18
```
19

20
**Usage Examples:**
21

22
```bash
23
# Update current project
24
cd my-existing-project
25
npx @js-lib/cli update
26

27
# Will update:
28
# - Build configuration files
29
# - Package.json scripts and dependencies
30
# - Linting and formatting configuration  
31
# - CI/CD workflows
32
# - Preserve custom source code and tests
33
```
34

35
### Update Process
36

37
The CLI handles project updates through the following process:
38

39
1. **Configuration Loading**: Reads existing `jslib.json` configuration file  
40
2. **Version Update**: Updates CLI version metadata in project configuration
41
3. **Template Application**: Applies latest template files based on project type (js/ts)
42
4. **Dependency Updates**: Updates package.json dependencies to latest versions
43
5. **Configuration Sync**: Updates build tools and linting configuration
44
6. **Preservation**: Carefully preserves all custom source code and tests
45

46
### Configuration File
47

48
Projects store metadata in `jslib.json` to enable updates:
49

50
```json
51
{
52
  "pathname": "my-project",
53
  "name": "My Project", 
54
  "npmname": "my-project",
55
  "umdname": "MyProject",
56
  "username": "johndoe",
57
  "type": "js",
58
  "manager": "npm",
59
  "version": "3.0.6"
60
}
61
```
62

63
### Update Process
64

65
The update process follows these steps:
66

67
1. **Validation**: Confirms `jslib.json` exists and is valid
68
2. **Version Check**: Updates CLI version in project metadata
69
3. **Template Application**: Applies latest template files based on project type
70
4. **Dependency Updates**: Updates package.json with latest dependencies
71
5. **Configuration Sync**: Updates build and tooling configuration files
72
6. **Preservation**: Preserves custom source code, tests, and documentation
73

74
### Updated Components
75

76
During updates, the following components are refreshed:
77

78
#### Build System
79
- Rollup configuration updates
80
- Package.json scripts and dependencies
81
- Build target and output configuration
82

83
#### Code Quality Tools
84
- ESLint configuration and rules
85
- Prettier formatting configuration  
86
- Husky git hooks setup
87
- lint-staged configuration
88

89
#### Testing Framework
90
- Mocha test configuration
91
- Coverage reporting setup (Istanbul/NYC)
92
- Test scripts and utilities
93

94
#### CI/CD Pipeline
95
- GitHub Actions workflow updates
96
- Node.js version matrix updates
97
- Automated testing and publishing
98

99
#### Root Files
100
- README.md template updates
101
- License and changelog templates
102
- Git ignore patterns
103
- Editor configuration
104

105
### Error Handling
106

107
The update process includes comprehensive error handling:
108

109
- **Missing Configuration**: Clear error if `jslib.json` is not found
110
- **Invalid JSON**: Validation and error messages for malformed configuration
111
- **File Conflicts**: Safe handling of existing customizations
112
- **Permission Issues**: Graceful handling of file system permissions
113
- **Backup Strategy**: Automatic backup of critical files before updates
114

115
### Selective Updates
116

117
The update process is intelligent about preserving customizations:
118

119
- **Source Code**: Never modified during updates
120
- **Tests**: Preserved with framework updates only
121
- **Documentation**: Custom content preserved, templates updated
122
- **Configuration**: Merged intelligently with new defaults
123
- **Dependencies**: Updated while preserving custom additions
124

125
### Compatibility
126

127
Updates maintain backward compatibility:
128

129
- **Node.js Versions**: Respects minimum version requirements
130
- **API Changes**: Handles breaking changes in dependencies gracefully
131
- **File Structure**: Maintains existing project organization
132
- **Custom Scripts**: Preserves custom package.json scripts