:semver()

The :semver() pseudo-class matches packages based on semver comparisons. By default it compares against the package version field, but it can be configured to compare any semver-like value. It also supports range-vs-range functions (subset, intersects) that operate on edges by comparing dependency specifier ranges.

Syntax

:semver(<range>)
:semver(<range>, <function>)
:semver(<range>, <function>, <custom-attribute-selector>)

Parameters

Parameter	Description	Default
`range`	The semver range to compare against	(required)
`function`	Comparison function	`satisfies`
`custom-attribute-selector`	A different property to compare	`version`

Comparison functions

Function	Description	Operates on
`satisfies`	Version satisfies the range (default)	nodes
`eq`	Version exactly equals the range	nodes
`neq`	Version does not equal the range	nodes
`gt`	Version is greater than the range	nodes
`gte`	Version is greater than or equal to the range	nodes
`lt`	Version is less than the range	nodes
`lte`	Version is less than or equal to the range	nodes
`intersects`	Edge’s range intersects with the provided range	edges
`subset`	Edge’s range is a subset of the provided range	edges

Examples

Basic range matching

Find packages satisfying ^1.0.0:

$ vlt query ':semver(^1.0.0)'

Exact version matching

Find packages at exactly version 2.0.0:

$ vlt query ':semver(2.0.0, eq)'

Version comparison

Find packages greater than version 5:

$ vlt query ':semver(5.0.0, gt)'

Range-vs-range comparison

The intersects and subset functions compare two ranges rather than a version against a range. By default they operate on edges using the dependency specifier (bareSpec), making it possible to query which declared dependency ranges relate to a given range.

Find edges whose declared range is a subset of >=2:

$ vlt query ':semver(>=2, subset)'

Find edges whose declared range intersects ^3:

$ vlt query ':semver(^3, intersects)'

When a custom attribute is provided, intersects and subset compare against that manifest property value as a range:

$ vlt query ':semver(>=20, subset, :attr(engines, [node]))'

Custom property comparison

Match packages whose engines.node field satisfies ^22:

$ vlt query ':semver(^22, satisfies, :attr(engines, [node]))'

What gets selected

Given:

my-app
├── react@18.2.0
├── react-dom@18.2.0
├── typescript@5.3.0
└── lodash@4.17.21

Query	Selected
`:semver(^18.0.0)`	react, react-dom
`:semver(5.0.0, gte)`	typescript
`:semver(^4.0.0)`	lodash

Combining with other selectors

Find direct dependencies with version >= 18:

$ vlt query ':root > :semver(18.0.0, gte)'

On this page