Skip to content

Commit 436f945

Browse files
JamieMasonJamieMason
committed
docs(site): add v14 migration guide
1 parent 02755d7 commit 436f945

1 file changed

Lines changed: 350 additions & 0 deletions

File tree

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

Lines changed: 350 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,350 @@
1+
---
2+
title: Migrate to 14
3+
sidebar:
4+
badge: New
5+
---
6+
7+
```bash
8+
npm install --save-dev syncpack@alpha
9+
```
10+
11+
## Command Changes
12+
13+
### `list-mismatches` → `lint`
14+
15+
`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`.
16+
17+
```bash
18+
# v13
19+
syncpack list-mismatches --types prod,dev
20+
# v14
21+
syncpack lint --dependency-types prod,dev
22+
```
23+
24+
### `lint-semver-ranges` → `lint`
25+
26+
`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.
27+
28+
```bash
29+
# v13
30+
syncpack lint-semver-ranges
31+
# v14
32+
syncpack lint
33+
```
34+
35+
### `fix-mismatches` → `fix`
36+
37+
`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`.
38+
39+
```bash
40+
# v13
41+
syncpack fix-mismatches
42+
# v14
43+
syncpack fix
44+
```
45+
46+
### `set-semver-ranges` → `fix`
47+
48+
`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.
49+
50+
```bash
51+
# v13
52+
syncpack set-semver-ranges
53+
# v14
54+
syncpack fix
55+
```
56+
57+
### `prompt` → Removed
58+
59+
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`.
60+
61+
```bash
62+
# v13
63+
syncpack prompt
64+
# v14
65+
# Not yet implemented
66+
```
67+
68+
## CLI Option Changes
69+
70+
### `--types` → `--dependency-types`
71+
72+
Renamed for consistency and also to differentiate it from other types such as specifier types.
73+
74+
```bash
75+
# v13
76+
syncpack list-mismatches --types prod,dev
77+
# v14
78+
syncpack lint --dependency-types prod,dev
79+
```
80+
81+
### `--specs` → `--specifier-types`
82+
83+
Renamed for consistency.
84+
85+
```bash
86+
# v13
87+
syncpack format --specs exact,range
88+
# v14
89+
syncpack format --specifier-types exact,range
90+
```
91+
92+
### `--filter` → `--dependencies`
93+
94+
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.
95+
96+
```bash
97+
# v13
98+
syncpack list-mismatches --filter "^@types\/.+"
99+
# v14
100+
syncpack lint --dependencies "@types/**"
101+
```
102+
103+
## Config Changes
104+
105+
### `dependencyTypes` removed
106+
107+
The `dependencyTypes` config has been removed in favour of using `versionGroups` config, which achieves the same result:
108+
109+
```jsonc
110+
{
111+
// Removed in v14
112+
"dependencyTypes": ["prod", "dev", "peer"],
113+
// Use instead
114+
"versionGroups": [
115+
{
116+
"label": "Ignore everything except dependencies, devDependencies, and peerDependencies",
117+
"dependencies": ["!prod", "!dev", "!peer"],
118+
"isIgnored": true,
119+
},
120+
],
121+
}
122+
```
123+
124+
Or use the `--dependency-types` CLI option to filter on an ad hoc basis:
125+
126+
```bash
127+
syncpack lint --dependency-types prod,dev,peer
128+
```
129+
130+
### `specifierTypes` removed
131+
132+
The `specifierTypes` config has been removed in favour of using `versionGroups` config, which achieves the same result:
133+
134+
```jsonc
135+
{
136+
// Removed in v14
137+
"specifierTypes": ["exact", "range"]
138+
// Use instead
139+
"versionGroups": [
140+
{
141+
"label": "Ignore everything except exact (1.2.3) or range (>=1.2.3, ~1.2.3 etc) specifier types",
142+
"specifierTypes": ["!exact", "!range"]
143+
"isIgnored": true,
144+
},
145+
],
146+
}
147+
```
148+
149+
Or use the `--specifier-types` CLI option to filter on an ad hoc basis:
150+
151+
```bash
152+
syncpack format --specifier-types exact,range
153+
```
154+
155+
### `lintFormatting` removed
156+
157+
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`.
158+
159+
`format` handles formatting, `lint` and `fix` handle version issues.
160+
161+
```jsonc
162+
{
163+
// Removed in v14
164+
"lintFormatting": false,
165+
}
166+
```
167+
168+
```bash
169+
# Check if formatting needed (exit 1 if needed)
170+
syncpack format --check
171+
# Safely see what formatting fixes would look like
172+
syncpack format --dry-run
173+
# Write formatting fixes to disk
174+
syncpack format
175+
```
176+
177+
### `lintSemverRanges` removed
178+
179+
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.
180+
181+
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.
182+
183+
```jsonc
184+
{
185+
// Removed in v14
186+
"lintSemverRanges": false,
187+
}
188+
```
189+
190+
### `lintVersions` → Always enabled
191+
192+
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.
193+
194+
This option is redundant in V14.
195+
196+
```jsonc
197+
{
198+
// Removed in v14
199+
"lintVersions": false,
200+
}
201+
```
202+
203+
## Migrating from older versions
204+
205+
### Version 11.2.1
206+
207+
#### `workspace` dependency type renamed to `local`
208+
209+
The `workspace` dependency type has been renamed to `local` for clarity.
210+
211+
```bash
212+
# v11.2.0 and earlier
213+
syncpack list --types prod,workspace
214+
# v14
215+
syncpack lint --dependency-types prod,local
216+
```
217+
218+
### Version 9.0.0
219+
220+
#### CLI Options Replaced
221+
222+
Individual boolean flags replaced with `--dependency-types` option:
223+
224+
```bash
225+
# v8
226+
syncpack list --prod --dev --peer
227+
# v14
228+
syncpack lint --dependency-types prod,dev,peer
229+
```
230+
231+
The following flags were removed:
232+
233+
- `-p, --prod`
234+
- `-d, --dev`
235+
- `-P, --peer`
236+
- `-R, --resolutions`
237+
- `-o, --overrides`
238+
- `-O, --pnpmOverrides`
239+
- `-w, --workspace`
240+
241+
#### Config Changes
242+
243+
Individual boolean properties replaced with `versionGroups` configuration:
244+
245+
```jsonc
246+
// v8
247+
{
248+
"dev": true,
249+
"overrides": false,
250+
"peer": true,
251+
"pnpmOverrides": false,
252+
"prod": true,
253+
"resolutions": false,
254+
"workspace": true
255+
}
256+
// v14 (use versionGroups instead)
257+
{
258+
"versionGroups": [
259+
{
260+
"label": "Ignore overrides",
261+
"dependencyTypes": ["overrides", "pnpmOverrides", "resolutions"],
262+
"isIgnored": true
263+
}
264+
]
265+
}
266+
```
267+
268+
### Version 8.0.0
269+
270+
#### pnpm overrides renamed
271+
272+
The `--overrides` option now refers to npm overrides. pnpm users must use `--pnpmOverrides` instead.
273+
274+
```bash
275+
# v7 (pnpm users)
276+
syncpack list --overrides
277+
# v14 (pnpm users)
278+
syncpack list --dependency-types pnpmOverrides
279+
# v14 (npm users)
280+
syncpack list --dependency-types overrides
281+
```
282+
283+
**Context:** v6.0.0 originally added `--overrides` for pnpm but read from the wrong property. npm later added their own `.overrides` property, so v8 split these into separate options.
284+
285+
### Version 7.0.0
286+
287+
#### Workspace dependency syncing enabled by default
288+
289+
Syncpack now syncs versions of locally developed packages by default. If package A depends on package B (both in your monorepo), syncpack will fix A's dependency to match B's actual version.
290+
291+
In v14, disable this behavior using `versionGroups`:
292+
293+
```jsonc
294+
{
295+
"versionGroups": [
296+
{
297+
"label": "Ignore .version properties of local packages",
298+
"dependencyTypes": ["local"],
299+
"isIgnored": true,
300+
},
301+
],
302+
}
303+
```
304+
305+
Or exclude `local` when using CLI flags:
306+
307+
```bash
308+
# v14
309+
syncpack lint --dependency-types '!local'
310+
```
311+
312+
### Version 6.0.0
313+
314+
#### `resolutions` and `overrides` enabled by default
315+
316+
Yarn's `resolutions` and pnpm's `overrides` fields are now processed by default.
317+
318+
In v14, exclude them using `versionGroups`:
319+
320+
```jsonc
321+
{
322+
"versionGroups": [
323+
{
324+
"label": "Ignore overrides",
325+
"dependencyTypes": ["resolutions", "overrides", "pnpmOverrides"],
326+
"isIgnored": true,
327+
},
328+
],
329+
}
330+
```
331+
332+
Or via CLI:
333+
334+
```bash
335+
# v14
336+
syncpack lint --dependency-types dev,peer,prod
337+
```
338+
339+
### Version 3.0.0
340+
341+
#### `--source` option changed
342+
343+
Package locations now specified with repeatable `--source` option instead of positional arguments:
344+
345+
```bash
346+
# v2
347+
syncpack list './package.json' './packages/*/package.json'
348+
# v14
349+
syncpack list --source './package.json' --source './packages/*/package.json'
350+
```

0 commit comments

Comments
 (0)