Skip to content

Commit 2eb4f34

Browse files
JamieMasonJamieMason
committed
docs(site): add v14 migration guide
1 parent bc219eb commit 2eb4f34

1 file changed

Lines changed: 199 additions & 0 deletions

File tree

‎site/src/content/docs/guide/migrate-v14.mdx‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
---
2+
title: Migrate to 14
3+
---
4+
5+
```bash
6+
npm install --save-dev syncpack@alpha
7+
```
8+
9+
## Command Changes
10+
11+
### `list-mismatches` → `lint`
12+
13+
`list-mismatches` and `lint-semver-ranges` have been merged into a single `lint` command which checks whether every specifier matches the semver group and version group they belong to. The `lint` command no longer checks formatting, which is now handled by `syncpack format ––check`.
14+
15+
```bash
16+
# v13
17+
syncpack list-mismatches --types prod,dev
18+
# v14
19+
syncpack lint --dependency-types prod,dev
20+
```
21+
22+
### `lint-semver-ranges` → `lint`
23+
24+
`list-mismatches` and `lint-semver-ranges` have been merged into a single `lint` command which checks whether every specifier matches the semver group and version group they belong to. The `lint` command no longer checks formatting, which is now handled by `syncpack format ––check`. It's no longer possible to manage semver ranges without also checking version mismatches, because the two things are so closely linked. Changes to semver ranges affect which versions are considered valid and can indirectly cause version mismatches, so they are now always checked and changed together via the `lint` and `fix` commands.
25+
26+
```bash
27+
# v13
28+
syncpack lint-semver-ranges
29+
# v14
30+
syncpack lint
31+
```
32+
33+
### `fix-mismatches` → `fix`
34+
35+
`fix-mismatches` and `set-semver-ranges` have been merged into a single `fix` command which autofixes issue found by `syncpack lint`. The `fix` command no longer fixes formatting, which is now handled by `syncpack format`.
36+
37+
```bash
38+
# v13
39+
syncpack fix-mismatches
40+
# v14
41+
syncpack fix
42+
```
43+
44+
### `set-semver-ranges` → `fix`
45+
46+
`fix-mismatches` and `set-semver-ranges` have been merged into a single `fix` command which autofixes issue found by `syncpack lint`. The `fix` command no longer fixes formatting, which is now handled by `syncpack format`. It's no longer possible to manage semver ranges without also checking version mismatches, because the two things are so closely linked. Changes to semver ranges affect which versions are considered valid and can indirectly cause version mismatches, so they are now always checked and changed together via the `lint` and `fix` commands.
47+
48+
```bash
49+
# v13
50+
syncpack set-semver-ranges
51+
# v14
52+
syncpack fix
53+
```
54+
55+
### `prompt` → Removed
56+
57+
The `prompt` command is an interactive prompt which lists all current issues which syncpack can't fix automatically. It is not yet available in v14 and will be added at a later date. Syncpack can't automatically fix mismatches between specifiers it does not support, which are usually specifiers which are not semver, such as pnpm overrides, or complex semver specifiers like `^1.2.3 || ^2.0.0`.
58+
59+
```bash
60+
# v13
61+
syncpack prompt
62+
# v14
63+
# Not yet implemented
64+
```
65+
66+
## CLI Option Changes
67+
68+
### `--types` → `--dependency-types`
69+
70+
Renamed for consistency and also to differentiate it from other types such as specifier types.
71+
72+
```bash
73+
# v13
74+
syncpack list-mismatches --types prod,dev
75+
# v14
76+
syncpack lint --dependency-types prod,dev
77+
```
78+
79+
### `--specs` → `--specifier-types`
80+
81+
Renamed for consistency.
82+
83+
```bash
84+
# v13
85+
syncpack format --specs exact,range
86+
# v14
87+
syncpack format --specifier-types exact,range
88+
```
89+
90+
### `--filter` → `--dependencies`
91+
92+
This has been renamed to `dependencies` to match the equivalent property of version groups and semver groups. Regular expressions are no longer supported and instead a glob pattern should be provided in the same way as they are for version groups and semver groups.
93+
94+
```bash
95+
# v13
96+
syncpack list-mismatches --filter "^@types\/.+"
97+
# v14
98+
syncpack lint --dependencies "@types/**"
99+
```
100+
101+
## Config Changes
102+
103+
### `dependencyTypes` removed
104+
105+
The `dependencyTypes` config has been removed in favour of using `versionGroups` config, which achieves the same result:
106+
107+
```jsonc
108+
{
109+
// Removed in v14
110+
"dependencyTypes": ["prod", "dev", "peer"],
111+
// Use instead
112+
"versionGroups": [
113+
{
114+
"label": "Ignore everything except dependencies, devDependencies, and peerDependencies",
115+
"dependencies": ["!prod", "!dev", "!peer"],
116+
"isIgnored": true,
117+
},
118+
],
119+
}
120+
```
121+
122+
Or use the `--dependency-types` CLI option to filter on an ad hoc basis:
123+
124+
```bash
125+
syncpack lint --dependency-types prod,dev,peer
126+
```
127+
128+
### `specifierTypes` removed
129+
130+
The `specifierTypes` config has been removed in favour of using `versionGroups` config, which achieves the same result:
131+
132+
```jsonc
133+
{
134+
// Removed in v14
135+
"specifierTypes": ["exact", "range"]
136+
// Use instead
137+
"versionGroups": [
138+
{
139+
"label": "Ignore everything except exact (1.2.3) or range (>=1.2.3, ~1.2.3 etc) specifier types",
140+
"specifierTypes": ["!exact", "!range"]
141+
"isIgnored": true,
142+
},
143+
],
144+
}
145+
```
146+
147+
Or use the `--specifier-types` CLI option to filter on an ad hoc basis:
148+
149+
```bash
150+
syncpack format --specifier-types exact,range
151+
```
152+
153+
### `lintFormatting` removed
154+
155+
The `lint` command no longer checks formatting, only version mismatches, so the `lintFormatting` option is no longer needed. If you don't want to lint or fix formatting, you can just not use `syncpack format` or `syncpack format --check`.
156+
157+
`format` handles formatting, `lint` and `fix` handle version issues.
158+
159+
```jsonc
160+
{
161+
// Removed in v14
162+
"lintFormatting": false,
163+
}
164+
```
165+
166+
```bash
167+
# Check if formatting needed (exit 1 if needed)
168+
syncpack format --check
169+
# Safely see what formatting fixes would look like
170+
syncpack format --dry-run
171+
# Write formatting fixes to disk
172+
syncpack format
173+
```
174+
175+
### `lintSemverRanges` removed
176+
177+
It's no longer possible to manage semver ranges without also checking version mismatches, because the two things are so closely linked. Changes to semver ranges affect which versions are considered valid and can indirectly cause version mismatches, so they are now always checked and changed together via the `lint` and `fix` commands.
178+
179+
V14 will always lint semver ranges when checking for version mismatches, but this will only apply to you if you have `semverGroups` defined. Let's say your project has `react` installed in three places: two of them use exact versions (`19.1.0` and `19.1.1`) and one of them belongs to a Semver Group which requires a `^` range so has a version of `^19.1.0`. Syncpack will synchronise these versions so that the highest version of `19.1.1` is used everywhere, while respecting the Semver Group requirement of `^19.1.1` being used for the member of that group.
180+
181+
```jsonc
182+
{
183+
// Removed in v14
184+
"lintSemverRanges": false,
185+
}
186+
```
187+
188+
### `lintVersions` → Always enabled
189+
190+
It's no longer possible to manage semver ranges without also checking version mismatches, because the two things are so closely linked. Changes to semver ranges affect which versions are considered valid and can indirectly cause version mismatches, so they are now always checked and changed together via the `lint` and `fix` commands.
191+
192+
This option is redundant in V14.
193+
194+
```jsonc
195+
{
196+
// Removed in v14
197+
"lintVersions": false,
198+
}
199+
```

0 commit comments

Comments
 (0)