Combinators

Combinators define relationships between packages in the dependency graph. They work similarly to CSS combinators but describe dependency relationships instead of DOM hierarchy.

Syntax

Combinator	Name	Description
>	Child	Direct dependencies of the previously selected nodes
(space)	Descendant	All direct & transitive dependencies
~	Sibling	Direct dependencies of all dependents of the previously selected nodes

Child combinator >

Matches packages that are direct dependencies of the previously selected nodes. Only one level deep.

Terminal

$ vlt query ':root > *'

Given this dependency graph:

my-app
├── [email protected]
│   └── [email protected]
│       └── [email protected]
└── [email protected]

:root > * selects only direct dependencies:

my-app
├── [email protected]          ✅ direct dependency of root
│   └── [email protected]
│       └── [email protected]
└── [email protected]      ✅ direct dependency of root

Chaining child combinators

You can chain > to select at specific depths:

Terminal

$ vlt query ':root > * > *'

my-app
├── [email protected]
│   └── [email protected]    ✅ grandchild of root
│       └── [email protected]
└── [email protected]

Descendant combinator (space)

Matches all packages that are direct or transitive dependencies of the previously selected nodes. Any depth.

Terminal

$ vlt query ':root [name=js-tokens]'

my-app
├── [email protected]
│   └── [email protected]
│       └── [email protected]   ✅ transitive dependency of root
└── [email protected]

Descendant vs. child

Terminal

# Direct deps only
$ vlt query ':root > [name=js-tokens]'
# → no results (js-tokens is not a direct dependency)

# All transitive deps

$ vlt query ':root [name=js-tokens]'

# → [email protected] (found transitively)

Sibling combinator ~

Matches packages that are direct dependencies of all dependents of the previously selected nodes. In other words: “other packages that share the same parent.”

Terminal

$ vlt query '[name=react] ~ *'

Given:

my-app
├── [email protected]
├── [email protected]
└── [email protected]

[name=react] ~ * selects siblings of react (other direct deps of the same parent):

my-app
├── [email protected]
├── [email protected]       ✅ sibling of react
└── [email protected]       ✅ sibling of react

Combining with selectors

Combinators are most powerful when combined with attribute selectors and pseudo-classes:

Find all direct dependencies that are outdated:

Terminal

$ vlt query ':root > :outdated'

Find workspaces that depend on packages with CVEs:

Terminal

$ vlt query ':workspace > :cve(*)'

Find all transitive dependencies of a specific package:

Terminal

$ vlt query '[name=react] *'

See also

• Pseudo-state Selectors — :root, :project, :workspace
• :has() pseudo-class — filter by descendant relationships