You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- ✘ Instance depends on a local package whose package.json version is not exact semver
8
7
- ? We can't know what the version should be
8
+
9
+
This status indicates that a dependency instance references a locally-developed package within the monorepo, but that local package has an invalid or non-semantic version in its package.json file.
10
+
11
+
When syncpack analyzes dependencies that reference local packages (packages developed within the same monorepo), it expects the local package to have a valid semantic version number in its package.json. If the local package's version is not a proper semantic version, syncpack cannot determine what version the dependent packages should reference.
12
+
13
+
For example, if you have a local package `@myorg/utils` with an invalid version:
14
+
15
+
```json
16
+
{
17
+
"name": "@myorg/utils",
18
+
"version": "latest"
19
+
}
20
+
```
21
+
22
+
And another package tries to depend on it:
23
+
24
+
```json
25
+
{
26
+
"dependencies": {
27
+
"@myorg/utils": "1.0.0"
28
+
}
29
+
}
30
+
```
31
+
32
+
The dependent package would receive this status because syncpack cannot verify whether `"1.0.0"` is correct when the local package's version is `"latest"` (which is not a valid semantic version).
33
+
34
+
This is considered an unfixable error because:
35
+
36
+
1.**Unknown target version**: Syncpack cannot determine what the correct version should be since the local package doesn't have a valid semantic version
37
+
2.**Manual intervention required**: A human needs to decide what the local package's version should be
38
+
3.**Root cause in local package**: The problem exists in the local package's version definition, not in the dependency reference
39
+
4.**Ambiguous resolution**: There's no algorithmic way to determine the intended version
40
+
41
+
Common invalid version formats that cause this status:
42
+
43
+
-`"version": "latest"`
44
+
-`"version": "next"`
45
+
-`"version": "experimental"`
46
+
-`"version": ""`
47
+
- Missing version property entirely
48
+
- Non-string version values
49
+
50
+
To resolve this issue:
51
+
52
+
1.**Fix the local package**: Update the local package's package.json to use a valid semantic version (e.g., `"1.0.0"`, `"2.1.3"`)
53
+
2.**Review dependents**: Once the local package has a valid version, syncpack can then analyze and potentially fix the dependent packages
54
+
3.**Establish version policy**: Ensure all local packages maintain proper semantic versioning
55
+
56
+
This status commonly occurs when:
57
+
58
+
- Local packages are in early development with placeholder versions
59
+
- Package.json files are manually edited with invalid version strings
60
+
- Build processes generate invalid version numbers
61
+
- Migration from non-semantic versioning systems leaves invalid versions
62
+
63
+
Until the local package has a valid semantic version, syncpack cannot provide guidance on what the dependent packages should specify, making this an unfixable situation that requires manual intervention.
- ✘ An instance of the same dependency was not found in any of the snapped to packages
9
8
- ! This is a misconfiguration resulting in this instance being orphaned
9
+
10
+
This status indicates that a dependency instance belongs to a snapTo version group, but the dependency is not found in any of the packages that this group is configured to "snap to". This creates an orphaned dependency that cannot follow its intended snapTo target.
11
+
12
+
SnapTo version groups are designed to make dependencies automatically follow the versions used by specific "target" packages in your monorepo. However, when the target packages don't actually use the dependency in question, syncpack cannot determine what version should be used.
13
+
14
+
For example, if you have a snapTo configuration like this:
And your main app only has some of these dependencies:
29
+
30
+
```json
31
+
{
32
+
"devDependencies": {
33
+
"prettier": "^3.0.0",
34
+
"eslint": "^8.45.0"
35
+
}
36
+
}
37
+
```
38
+
39
+
But another package in the snapTo group has:
40
+
41
+
```json
42
+
{
43
+
"devDependencies": {
44
+
"typescript": "^5.0.0"
45
+
}
46
+
}
47
+
```
48
+
49
+
The `typescript` dependency would receive this status because:
50
+
51
+
1.**SnapTo group membership**: It belongs to a snapTo version group targeting the main app
52
+
2.**Missing target**: The main app doesn't have `typescript` in its dependencies
53
+
3.**No reference version**: Syncpack cannot determine what version `typescript` should use
54
+
4.**Orphaned dependency**: The dependency has no snapTo target to follow
55
+
56
+
This is considered a suspect status (indicating a configuration issue) because:
57
+
58
+
1.**Configuration mismatch**: The snapTo group includes dependencies that the target packages don't use
59
+
2.**Impossible synchronization**: Syncpack cannot synchronize with a non-existent target
60
+
3.**Manual intervention required**: The configuration needs to be corrected
61
+
4.**Ambiguous intent**: It's unclear what the intended behavior should be
62
+
63
+
Common scenarios that lead to this status:
64
+
65
+
**Target package changes:**
66
+
67
+
- Target packages remove dependencies that are still listed in snapTo groups
68
+
- Dependencies are moved between different sections (dependencies vs devDependencies) in target packages
69
+
- Target packages are refactored and no longer use certain tools
70
+
71
+
**Configuration drift:**
72
+
73
+
- SnapTo groups include overly broad dependency patterns
74
+
- Dependencies are added to snapTo groups without verifying they exist in targets
75
+
- Copy-paste configuration errors include dependencies not used by targets
76
+
77
+
**Package evolution:**
78
+
79
+
- Target packages evolve and drop certain dependencies
80
+
- New dependencies are added to snapTo groups without updating targets
81
+
- Technology changes make certain dependencies obsolete in target packages
82
+
83
+
To resolve this issue, you have several options:
84
+
85
+
1.**Add dependency to target**: If the target package should have this dependency, add it:
86
+
87
+
```json
88
+
{
89
+
"devDependencies": {
90
+
"prettier": "^3.0.0",
91
+
"eslint": "^8.45.0",
92
+
"typescript": "^5.0.0"
93
+
}
94
+
}
95
+
```
96
+
97
+
2.**Remove from snapTo group**: If the dependency shouldn't follow the target, remove it from the snapTo configuration:
98
+
99
+
```json
100
+
{
101
+
"versionGroups": [
102
+
{
103
+
"label": "Follow Main App Tools",
104
+
"dependencies": ["prettier", "eslint"],
105
+
"snapTo": ["packages/main-app"]
106
+
}
107
+
]
108
+
}
109
+
```
110
+
111
+
3.**Change snapTo target**: Point to different packages that do have this dependency:
112
+
113
+
```json
114
+
{
115
+
"versionGroups": [
116
+
{
117
+
"label": "Follow TypeScript Tools",
118
+
"dependencies": ["typescript"],
119
+
"snapTo": ["packages/api", "packages/web"]
120
+
}
121
+
]
122
+
}
123
+
```
124
+
125
+
4.**Use different strategy**: Switch to a different version group strategy:
126
+
- Use `highestSemver` to follow the highest version found across all packages
127
+
- Use `pinVersion` to enforce a specific version
128
+
- Use `sameRange` to ensure compatibility without following a specific target
129
+
130
+
This commonly occurs when:
131
+
132
+
- SnapTo configurations are created with broad dependency patterns without verification
133
+
- Target packages are refactored but snapTo configurations aren't updated
134
+
- Dependencies are deprecated in target packages but not removed from snapTo groups
135
+
- Development workflows change but configuration doesn't reflect the new reality
136
+
- Multiple teams manage different parts of the monorepo with different tooling preferences
137
+
138
+
This status serves as a warning that your snapTo configuration references dependencies that don't exist in the target packages, making the snapTo relationship impossible to maintain. The dependency becomes "orphaned" and cannot benefit from the intended version synchronization until the configuration is corrected.
139
+
140
+
The key insight is that snapTo groups should only include dependencies that actually exist in the target packages, ensuring that there's always a reference version to follow.
- ✘ Instance mismatches highest/lowest semver in its group
7
+
8
+
This status indicates that a dependency instance has a different version than the highest (or lowest, depending on configuration) semantic version found among all instances of that dependency across the monorepo.
9
+
10
+
When syncpack analyzes all instances of a particular dependency, it identifies which instance has the highest semantic version number. For version groups configured to use the "highest semver" strategy, all instances should be updated to match this highest version to ensure consistency across the monorepo.
11
+
12
+
For example, if you have these instances of `lodash` across your monorepo:
Packages B and C would receive this status because their versions (`4.17.19` and `4.16.0`) don't match the highest version found (`4.17.20`).
19
+
20
+
This is considered a fixable error because syncpack can automatically update the outdated dependency versions to match the highest version found. This ensures that:
21
+
22
+
1.**Version consistency**: All packages use the same version of shared dependencies
23
+
2.**Latest features**: All packages benefit from the newest features and bug fixes
24
+
3.**Reduced bundle size**: Package managers can deduplicate dependencies more effectively
25
+
4.**Simplified maintenance**: Fewer versions to track and update
26
+
27
+
To fix this issue, syncpack will update the dependency versions to match the highest version found, while preserving any semver range formatting specified by semver group configuration.
28
+
29
+
This commonly occurs when:
30
+
31
+
- Different packages are updated at different times
32
+
- New dependencies are added with older versions
33
+
- Manual package updates create version drift across the monorepo
34
+
- Dependencies are installed independently without coordination
35
+
36
+
For "lowest semver" configurations, the same logic applies but syncpack will update instances to match the lowest version found instead of the highest.
- ✘ Instance mismatches the version of its locally-developed package
7
+
8
+
This status indicates that a dependency instance has a different version than the locally-developed package it references within the same monorepo.
9
+
10
+
When a package in your monorepo depends on another package that is also developed locally within the same monorepo, syncpack expects the dependency version to match the local package's version exactly. This ensures consistency between what's published and what's being depended upon internally.
11
+
12
+
For example, if your local package `@myorg/utils` has version `"1.2.3"` in its package.json, but another package in the monorepo specifies:
13
+
14
+
```json
15
+
{
16
+
"dependencies": {
17
+
"@myorg/utils": "1.1.0"
18
+
}
19
+
}
20
+
```
21
+
22
+
This would receive the DiffersToLocal status because the referenced version (`1.1.0`) doesn't match the actual local version (`1.2.3`).
23
+
24
+
This is considered a fixable error because syncpack can automatically update the dependency version to match the local package's current version. This ensures that:
25
+
26
+
1.**Internal consistency**: All internal dependencies reference the correct versions of local packages
27
+
2.**Development accuracy**: Local development reflects the actual package relationships
28
+
3.**Build reliability**: The versions used during development match what would be used in production
29
+
30
+
To fix this issue, syncpack will update the dependency version to match the current version of the local package, ensuring your monorepo maintains internal version consistency.
31
+
32
+
This commonly occurs when:
33
+
34
+
- A local package's version is bumped but dependent packages aren't updated
35
+
- Manual edits to package.json files introduce version mismatches
36
+
- Merge conflicts result in inconsistent version references
- ✘ Instance is older than highest semver published to the registry
7
+
8
+
This status indicates that a dependency instance is using an outdated version compared to what's available on the npm registry. Syncpack has detected that a newer version of the dependency has been published and is eligible for update according to your configuration.
9
+
10
+
This occurs when syncpack queries the npm registry and finds that there are newer versions available that match your update criteria (such as respecting major version boundaries for dependencies, or allowing any updates for devDependencies).
11
+
12
+
For example, if your package.json contains:
13
+
14
+
```json
15
+
{
16
+
"dependencies": {
17
+
"react": "^18.1.0"
18
+
}
19
+
}
20
+
```
21
+
22
+
But the npm registry shows that `react@18.2.0` is available, syncpack would mark this dependency with the DiffersToNpmRegistry status because a newer patch version is available within the same major version range.
23
+
24
+
This is considered a fixable error because syncpack can automatically update the dependency version to the latest available version that matches your update policy. This ensures that:
25
+
26
+
1.**Security updates**: You benefit from the latest security patches and bug fixes
27
+
2.**Performance improvements**: Newer versions often include performance optimizations
28
+
3.**Feature access**: You can use the latest features and improvements
29
+
4.**Maintenance currency**: Your dependencies stay reasonably up-to-date
30
+
31
+
To fix this issue, syncpack will update the dependency version to the latest eligible version found on the npm registry, while preserving any semver range formatting specified by your semver group configuration.
32
+
33
+
The specific update eligibility is determined by your syncpack configuration, which may include:
34
+
35
+
- Respecting semver ranges (e.g., only updating within the current major version)
36
+
- Different update policies for different dependency types (dependencies vs devDependencies)
37
+
- Specific inclusion or exclusion rules for certain packages
38
+
39
+
This status is particularly useful for maintaining security and getting bug fixes, as it helps identify when your dependencies have fallen behind the latest published versions.
This status indicates that a dependency instance has a different version than what is specified in its pinned version group configuration.
9
+
10
+
Pinned version groups allow you to enforce that specific dependencies always use an exact version across your entire monorepo. When a dependency is configured to be pinned, syncpack expects all instances of that dependency to use the identical version specifier defined in the pinned configuration.
11
+
12
+
For example, if you have a pinned version group configured like this:
13
+
14
+
```json
15
+
{
16
+
"versionGroups": [
17
+
{
18
+
"label": "Critical Infrastructure",
19
+
"dependencies": ["react", "react-dom"],
20
+
"pinVersion": "18.2.0"
21
+
}
22
+
]
23
+
}
24
+
```
25
+
26
+
But one of your packages specifies:
27
+
28
+
```json
29
+
{
30
+
"dependencies": {
31
+
"react": "18.1.0"
32
+
}
33
+
}
34
+
```
35
+
36
+
This would receive the DiffersToPin status because the actual version (`18.1.0`) doesn't match the pinned version (`18.2.0`).
37
+
38
+
This is considered a fixable error because syncpack can automatically update the dependency version to match the pinned version specified in the configuration. This ensures that:
39
+
40
+
1.**Version enforcement**: Critical dependencies maintain exactly the versions you've specified
41
+
2.**Consistency**: All packages use identical versions of pinned dependencies
42
+
3.**Stability**: Important infrastructure dependencies remain at tested, approved versions
43
+
4.**Compliance**: Your monorepo adheres to architectural decisions about version pinning
44
+
45
+
To fix this issue, syncpack will update the dependency version to exactly match the pinned version specified in your configuration, ensuring that critical packages maintain the stability and predictability that pinning is designed to provide.
46
+
47
+
This commonly occurs when:
48
+
49
+
- Dependencies are manually updated without considering pinned version constraints
50
+
- New packages are added that don't follow existing pinning rules
51
+
- Pinned version configurations are changed but existing packages aren't updated
52
+
- Merge conflicts introduce versions that don't match pinned requirements
53
+
54
+
Pinned versions are particularly useful for critical infrastructure dependencies where you want to ensure all packages use exactly the same tested version, such as React, build tools, or other foundational libraries where version consistency is crucial for stability.
0 commit comments