Skip to content

Commit

Permalink
feat(groups): manage intersecting range versions
Browse files Browse the repository at this point in the history
  • Loading branch information
@JamieMason
JamieMason committed Jun 4, 2023
1 parent f7c87a8 commit 96d6c6d
Show file tree
Hide file tree
Showing 34 changed files with 1,128 additions and 1,411 deletions.
266 changes: 49 additions & 217 deletions site/docs/config/version-groups.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,255 +3,87 @@ id: version-groups
title: versionGroups
---

import Pills from '@site/src/components/pill';
import DefaultDependencyTypes from '@site/src/partials/default-dependency-types.mdx';

# `versionGroups` object[]

:::info

Learn more in our [guide to Version Groups](../guide/version-groups.mdx)

:::

## `packages` string[]

<Pills required />

An array of strings which should match the `name` properties of your
package.json files. This is used in combination with the
[`dependencies`](#dependencies-string) property to determine which dependencies
should belong to this version group.

The strings can any combination of exact matches or
[minimatch](https://github.com/isaacs/minimatch) glob patterns:

```json
// match any package
["**"]

// match any package with a certain scope
["@my-repo/**"]

// match specific packages by name
["my-server", "my-client"]
```

## `dependencies` string[]

<Pills required />

An array of strings which should match the names of dependencies you've
installed or otherwise referenced in your package.json files. This is used in
combination with the [`packages`](#packages-string) property to determine which
dependencies should belong to this version group.

```json title="Example of which strings are matched against"
{
"name": "not-here",
"dependencies": { "HERE": "0.0.0" },
"devDependencies": { "HERE": "0.0.0" },
"overrides": { "HERE": "0.0.0" },
"peerDependencies": { "HERE": "0.0.0" },
"pnpm": { "overrides": { "HERE": "0.0.0" } },
"resolutions": { "HERE": "0.0.0" }
}
```

The strings can any combination of exact matches or
[minimatch](https://github.com/isaacs/minimatch) glob patterns:

```json title="Examples of valid values"
// match any dependency
["**"]

// match all dependencies with a certain scope
["@aws-sdk/**"]

// match specific dependencies by name
["react", "react-dom"]
```

:::tip

You can extend syncpack to look in more places by defining your own
[`customTypes`](./custom-types.mdx). If you do that, then the names of any
dependencies found by your `customTypes` can also be targeted using this field.

:::

## `dependencyTypes` string[]
Version groups are an array of objects which partition your monorepo into
isolated sections which each have their own rules/policy/strategy for how
versions should be managed.

<Pills optional />
There are 6 types of version groups:

Can be used in combination with the [`packages`](#packages-string) and
[`dependencies`](#dependencies-string) properties to narrow further which
dependencies should belong to this version group. When set, only dependencies
present in the named locations will be considered a match for this version
group.
- [Banned](./version-groups/banned.mdx)
- [Ignored](./version-groups/ignored.mdx)
- [Pinned](./version-groups/pinned.mdx)
- [Same Range](./version-groups/same-range.mdx)
- [Snapped To](./version-groups/snapped-to.mdx)
- [Standard](./version-groups/standard.mdx)

The possible values available by default are in the table below:

<DefaultDependencyTypes />

:::tip

If you define your own [`customTypes`](./custom-types.mdx), their names can also
be used in addition to those in the table above.

:::

In this example we define that all dependencies within `peerDependencies` in the
repo must use `"*"` as its version number, regardless of what versions of the
same dependencies might be used in `dependencies` or `devDependencies`.

```json title="Ensure peerDependencies always use *"
{
"versionGroups": [
{
"packages": ["**"],
"dependencies": ["**"],
"dependencyTypes": ["peer"],
"pinVersion": "*"
}
]
}
```

:::tip
:::info

Syncpack config files also support
[TypeScript IntelliSense](https://jamiemason.github.io/syncpack/config-file#typescript-intellisense).
Learn more in our [guide to Version Groups](../guide/version-groups.mdx)

:::

## `label` string
## Example

<Pills optional />
- Let's say your monorepo directly depends on `react`, 3 of your packages have
it under `dependencies` and another 2 have it under `peerDependencies`. Each
of those 5 specific places where `react` is depended on we refer to as an
"instance".
- Every instance of every dependency in your repo is assigned to the first
version group it matches.
- Each instance can only belong to one version group.
- If you do not define any version groups, or a given instance of a dependency
does not match any of them, it is assigned to an internal catch-all
[Standard](./version-groups/standard.mdx) version group.

A short name or description to be displayed in a header in syncpack's output,
above the dependencies which matched this group. If a `label` is not set, then
the order which this group appears in your config will be used instead.
Here is an example which uses every kind of version group:

```json title="Example where a label is used to give context to other Devs"
```json
{
"versionGroups": [
{
"label": "AWS dependencies must all share the same version",
// Pinned
"label": "Ensure AWS SDK dependencies always use the same version",
"packages": ["**"],
"dependencies": ["@aws-sdk/**"],
"pinVersion": "3.272.0"
}
]
}
```

## `isBanned` boolean

<Pills optional />

Remove dependencies which you've decided should never be used.

```json title="Completely ban a dependency from being used anywhere"
{
"versionGroups": [
},
{
// Banned
"label": "Please use lodash instead of underscore",
"packages": ["**"],
"dependencies": ["never-gonna"],
"dependencies": ["underscore"],
"isBanned": true
}
]
}
```

```json title="Ban a dependency from being used in production"
{
"versionGroups": [
{
"packages": ["my-fast-ui"],
"dependencies": ["huge-filesize-party"],
"dependencyTypes": ["prod"],
"isBanned": true
}
]
}
```

## `isIgnored` boolean

<Pills optional />

Have syncpack ignore these dependencies completely.

```json title="Hide dependencies from syncpack"
{
"versionGroups": [
},
{
// Ignored
"label": "Ignore issues in these dodgy packages",
"packages": ["oops-moment", "workaround"],
"dependencies": ["**"],
"isIgnored": true
}
]
}
```

## `pinVersion` string

<Pills optional />

Pin the version of all dependencies in this group to match this specific version
you've defined.

```json title="Ensure AWS dependencies always have the same version"
{
"versionGroups": [
{
"dependencies": ["@aws-sdk/**"],
"packages": ["**"],
"pinVersion": "3.272.0"
}
]
}
```

## `snapTo` string[]

<Pills optional />

Pin the version of all dependencies in this group to match the version used by
the package(s) named within the `snapTo` array. The values refer to the `name`
property of the package.json files developed in your monorepo.

Multiple values can be added to provide fallback packages to try in the event
that the dependency is not present in the earlier packages in the array.

```json title="Ensure all packages use whatever version mobile-app is using"
{
"versionGroups": [
},
{
// Snapped
"label": "Ensure all packages use whatever version the mobile-core package is using",
"dependencies": ["react", "react-native"],
"packages": ["**"],
"snapTo": ["mobile-app"]
}
]
}
```

## `preferVersion` string

<Pills optional />

Defaults to `highestSemver` but can be optionally changed to `lowestSemver`.

To set this as your standard policy, create a version group which applies to
every dependency as the last item in your `versionGroups` array. You can also
just set this for some of the packages if you need to.

```json title="Choose the lowest valid semver version when fixing mismatches"
{
"versionGroups": [
"snapTo": ["mobile-core"]
},
{
// Pinned
"label": "Use '*' under 'peerDependencies' everywhere",
"packages": ["**"],
"dependencies": ["**"],
"dependencyTypes": ["peer"],
"pinVersion": "*"
},
{
// Standard
"label": "Resolve mismatches here with the oldest version instead of the newest",
"dependencies": ["@vintage/**"],
"packages": ["**"],
"preferVersion": "lowestSemver"
}
Expand Down
67 changes: 67 additions & 0 deletions site/docs/config/version-groups/banned.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
---
id: banned
title: Banned
---

import Pills from '@site/src/components/pill';
import Packages from '@site/src/partials/version-group-config/packages.mdx';
import Dependencies from '@site/src/partials/version-group-config/dependencies.mdx';
import DependencyTypes from '@site/src/partials/version-group-config/dependency-types.mdx';
import Label from '@site/src/partials/version-group-config/label.mdx';

# Banned

Remove dependencies which you've decided should never be used.

:::info

- One of the possible values for the [`versionGroups`](../version-groups.mdx)
configuration array.
- Learn more in our [guide to Version Groups](../../guide/version-groups.mdx).

:::

## `isBanned` boolean

<Pills required />

```json title="Completely ban a dependency from being used anywhere"
{
"versionGroups": [
{
"packages": ["**"],
"dependencies": ["never-gonna"],
"isBanned": true
}
]
}
```

```json title="Ban a dependency from being used in production"
{
"versionGroups": [
{
"packages": ["my-fast-ui"],
"dependencies": ["huge-filesize-party"],
"dependencyTypes": ["prod"],
"isBanned": true
}
]
}
```

## `packages` string[]

<Packages />

## `dependencies` string[]

<Dependencies />

## `dependencyTypes` string[]

<DependencyTypes />

## `label` string

<Label />

0 comments on commit 96d6c6d

Please sign in to comment.