Skip to content

Commit 882ce73

Browse files
JamieMasonJamieMason
committed
docs(site): better explain name~version semantics
Closes #330
1 parent 9e85d25 commit 882ce73

1 file changed

Lines changed: 143 additions & 19 deletions

File tree

‎site/src/content/docs/config/custom-types.mdx‎

Lines changed: 143 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -53,53 +53,177 @@ This is how the default dependency types are defined:
5353
}
5454
```
5555

56-
## \[name\] <Badge text="Required" variant="danger" />
56+
Pick a strategy below based on the shape of your data.
5757

58-
The key of each custom type is its name, this is equivalent to the default names such as `prod` and `dev` and can be used in all of the same places those can:
58+
## `name@version`
59+
60+
A single string combining name and version, separated by `@`.
61+
62+
```json title="package.json"
63+
{
64+
"packageManager": "pnpm@7.27.0"
65+
}
66+
```
67+
68+
```json title=".syncpackrc.json"
69+
{
70+
"customTypes": {
71+
"packageManager": {
72+
"strategy": "name@version",
73+
"path": "packageManager"
74+
}
75+
}
76+
}
77+
```
78+
79+
### \[name\] <Badge text="Required" variant="danger" />
80+
81+
The name of the new dependency type you are adding to syncpack. Syncpack ships with built-in types like `prod`, `dev`, and `peer`; defining a custom type adds your chosen name to that list, ready to be referenced from:
5982

6083
1. `--dependency-types`
6184
1. `versionGroup.dependencyTypes`
6285
1. `semverGroup.dependencyTypes`
6386
1. `dependencyGroup.dependencyTypes`
6487

65-
## \[name\].path <Badge text="Required" variant="danger" />
66-
67-
Where the version can be found in each package.json file, such as `engines`, `packageManager` or `some.nested.property`.
88+
### \[name\].path <Badge text="Required" variant="danger" />
6889

69-
## \[name\].strategy <Badge text="Required" variant="danger" />
90+
The location in each package.json of the `"name@version"` string. Use dot notation for nested properties (eg. `packageManager`, `some.nested.property`).
7091

71-
A strategy defines how syncpack should read and write dependency names and versions.
92+
### \[name\].strategy <Badge text="Required" variant="danger" />
7293

73-
There are 3 to choose from:
94+
Must be `"name@version"`.
7495

75-
### `name@version`
96+
## `name~version`
7697

77-
The name and version are combined in a single string. Commonly seen in package manager specifications.
98+
The name and version live at two separate paths. Both must point directly to **string** values, not to a containing object.
7899

79100
```json title="package.json"
80101
{
81-
"packageManager": "pnpm@7.27.0"
102+
"devEngines": {
103+
"runtime": {
104+
"name": "node",
105+
"version": "22.11.0"
106+
}
107+
}
82108
}
83109
```
84110

85-
### `name~version`
111+
```json title=".syncpackrc.json"
112+
{
113+
"customTypes": {
114+
"devEnginesRuntime": {
115+
"strategy": "name~version",
116+
"namePath": "devEngines.runtime.name",
117+
"path": "devEngines.runtime.version"
118+
}
119+
}
120+
}
121+
```
122+
123+
A common mistake is pointing `path` at the containing object (`devEngines.runtime`) and `namePath` at `name` relative to it. Both paths are absolute from the package.json root and must resolve to strings.
124+
125+
### \[name\] <Badge text="Required" variant="danger" />
126+
127+
The name of the new dependency type you are adding to syncpack. Syncpack ships with built-in types like `prod`, `dev`, and `peer`; defining a custom type adds your chosen name to that list, ready to be referenced from:
128+
129+
1. `--dependency-types`
130+
1. `versionGroup.dependencyTypes`
131+
1. `semverGroup.dependencyTypes`
132+
1. `dependencyGroup.dependencyTypes`
133+
134+
### \[name\].path <Badge text="Required" variant="danger" />
135+
136+
The location in each package.json of the version string. Absolute from the package.json root; must point to a string.
137+
138+
### \[name\].namePath <Badge text="Required" variant="danger" />
86139

87-
The name and version are in different locations.
140+
The location in each package.json of the dependency name. Absolute from the package.json root; must point to a string.
141+
142+
### \[name\].strategy <Badge text="Required" variant="danger" />
143+
144+
Must be `"name~version"`.
145+
146+
## `version`
147+
148+
A bare version string with no name in the data. The custom type's **key** is used as the dependency name.
88149

89150
```json title="package.json"
90151
{
91-
"name": "some-local-package",
92-
"version": "12.4.2"
152+
"engines": {
153+
"node": "22.11.0"
154+
}
93155
}
94156
```
95157

96-
### `versionsByName`
158+
```json title=".syncpackrc.json"
159+
{
160+
"customTypes": {
161+
"node": {
162+
"strategy": "version",
163+
"path": "engines.node"
164+
}
165+
}
166+
}
167+
```
168+
169+
Here the dependency is reported as `node` because that is the custom type's key.
170+
171+
### \[name\] <Badge text="Required" variant="danger" />
172+
173+
The name of the new dependency type you are adding to syncpack. Syncpack ships with built-in types like `prod`, `dev`, and `peer`; defining a custom type adds your chosen name to that list, ready to be referenced from:
174+
175+
1. `--dependency-types`
176+
1. `versionGroup.dependencyTypes`
177+
1. `semverGroup.dependencyTypes`
178+
1. `dependencyGroup.dependencyTypes`
179+
180+
For the `version` strategy specifically, this name is also used as the dependency name in reports and grouping (since the data has no name field of its own).
181+
182+
### \[name\].path <Badge text="Required" variant="danger" />
97183

98-
Typical dependency objects where keys are package names and values are version strings.
184+
The location in each package.json of the version string. Use dot notation for nested properties (eg. `engines.node`).
185+
186+
### \[name\].strategy <Badge text="Required" variant="danger" />
187+
188+
Must be `"version"`.
189+
190+
## `versionsByName`
191+
192+
A typical dependency object where keys are package names and values are version strings.
99193

100194
```json title="package.json"
101195
{
102-
"pnpm": "10.10.0",
103-
"prettier": "3.5.3"
196+
"dependencies": {
197+
"pnpm": "10.10.0",
198+
"prettier": "3.5.3"
199+
}
200+
}
201+
```
202+
203+
```json title=".syncpackrc.json"
204+
{
205+
"customTypes": {
206+
"prod": {
207+
"strategy": "versionsByName",
208+
"path": "dependencies"
209+
}
210+
}
104211
}
105212
```
213+
214+
### \[name\] <Badge text="Required" variant="danger" />
215+
216+
The name of the new dependency type you are adding to syncpack. Syncpack ships with built-in types like `prod`, `dev`, and `peer`; defining a custom type adds your chosen name to that list, ready to be referenced from:
217+
218+
1. `--dependency-types`
219+
1. `versionGroup.dependencyTypes`
220+
1. `semverGroup.dependencyTypes`
221+
1. `dependencyGroup.dependencyTypes`
222+
223+
### \[name\].path <Badge text="Required" variant="danger" />
224+
225+
The location in each package.json of the `{ "name": "version" }` object. Use dot notation for nested properties (eg. `dependencies`, `pnpm.overrides`).
226+
227+
### \[name\].strategy <Badge text="Required" variant="danger" />
228+
229+
Must be `"versionsByName"`.

0 commit comments

Comments
 (0)