Reference

Classes

Monorepo

Defined in: index.ts:306

Class representing a Monorepo containing multiple workspaces.

Does not automatically look up the root, but that can be provided by running Config.load(), since it stops seeking the route when a vlt.json file is encountered.

Constructors

new Monorepo()

new Monorepo(projectRoot, options): Monorepo

Defined in: index.ts:325

Parameters

Returns

Monorepo

Properties

Accessors

config

Get Signature

get config(): WorkspaceConfigObject

Defined in: index.ts:343

Load the workspace definitions from vlt.json, else the root package.json, else pnpm-workspace.yaml (see resolveWSConfig), canonicalizing the result into the effective {[group:string]:string[]} form.

Eg:

• "src/*" => {packages:["src/*"]}
• {"apps": "src/*"} => {apps: ["src/*"]}

Returns

WorkspaceConfigObject

size

Get Signature

get size(): number

Defined in: index.ts:321

Number of Workspace objects loaded in this Monorepo

Returns

number

Methods

[asyncIterator]()

asyncIterator: AsyncGenerator<Workspace, void, void>

Defined in: index.ts:370

Iterating the Monorepo object yields the workspace objects, in as close to topological dependency order as possible.

Returns

AsyncGenerator<Workspace, void, void>

[iterator]()

iterator: Generator<Workspace, void, void>

Defined in: index.ts:356

Iterating the Monorepo object yields the workspace objects, in as close to topological dependency order as possible.

Returns

Generator<Workspace, void, void>

filter()

filter(__namedParameters): Generator<Workspace, void, unknown>

Defined in: index.ts:732

Filter the monorepo object yielding the workspace objects that matches either of the WorkspacesLoadedConfig options provided, in as close to topological dependency order as possible.

Parameters

Returns

Generator<Workspace, void, unknown>

get()

get(nameOrPath): undefined | Workspace

Defined in: index.ts:679

Get a loaded workspace by path or name.

Note that this can only return workspaces that were ingested via a previous call to Monorepo#load.

Parameters

Returns

undefined | Workspace

getDeps()

getDeps(ws, forceLoad): Workspace[]

Defined in: index.ts:595

Return the array of workspace dependencies that are found in the loaded set, for use in calculating dependency graph order for build operations.

This does not get the full set of dependencies, or expand any workspace: dependencies that are not loaded.

Bare semver specs are matched by name, and linked only when the local workspace version satisfies the range -- the same test @vltpkg/satisfies applies at resolution time, so the two agree on which deps are local. Specs that aren't parseable ranges, such as dist-tags, still match by name alone.

Call with the forceLoad param set to true to attempt a full load if any deps are not currently loaded.

Parameters

Returns

Workspace[]

group()

group(group): undefined | Set<Workspace>

Defined in: index.ts:669

Return the set of workspaces in the named group. If the group is not one we know about, then undefined is returned.

Parameters

Returns

undefined | Set<Workspace>

keys()

keys(): Generator<string, void, unknown>

Defined in: index.ts:720

Get all the keys (package names and paths) for loaded workspaces. Union of Monorepo#names and Monorepo#paths

Returns

Generator<string, void, unknown>

load()

load(query): this

Defined in: index.ts:397

By default, loads all workspaces reachable in the Monorepo.

If provided with one (string)or more (string[]) group names in the LoadQuery#groups field, then only Workspaces in the named group(s) will be considered. Note that group names are unique string matches, not globs.

If provided with a set of arbitrary path arguments, then only paths patching the provided pattern(s) will be included.

These two options intersect, so load({groups:'foo', paths:'./foo/[xy]*'}) will only load the workspaces in the group foo that match the paths glob.

Parameters

Returns

this

names()

names(): Generator<string, void, unknown>

Defined in: index.ts:686

get the list of all loaded workspace names used as keys

Returns

Generator<string, void, unknown>

onCycle()

onCycle(
   _ws, 
   _cycle, 
   _depPath): void

Defined in: index.ts:651

Parameters

Returns

void

paths()

paths(): Generator<string, void, unknown>

Defined in: index.ts:695

get the list of all loaded workspace paths used as keys

Returns

Generator<string, void, unknown>

run()

run<R>(operation, forceLoad): Promise<Map<Workspace, R>>

Defined in: index.ts:775

Run an operation asynchronously over all loaded workspaces

If the forceLoad param is true, then it will attempt to do a full load when encountering a workspace: dependency that isn't loaded.

Note that because the return type appears in the parameters of the operation function, it must be set explicitly either in the operation function signature or by calling run<MyType> or it'll fall back to unknown, similar to Array.reduce(), and for the same reason.

Type Parameters

Parameters

Returns

Promise<Map<Workspace, R>>

runSync()

runSync<R>(operation, forceLoad): Map<Workspace, R>

Defined in: index.ts:808

Run an operation synchronously over all loaded workspaces

If the forceLoad param is true, then it will attempt to do a full load when encountering a workspace: dependency that isn't loaded.

Note that because the return type appears in the parameters of the operation function, it must be set explicitly either in the operation function signature or by calling runSync<MyType> or it'll fall back to unknown, similar to Array.reduce(), and for the same reason.

Type Parameters

Parameters

Returns

Map<Workspace, R>

values()

values(): Generator<Workspace, void, unknown>

Defined in: index.ts:707

get the workspace objects in no particular order. this is ever so slightly faster than iterating, because it doesn't explore the graph to yield results in topological dependency order, and should be used instead when order doesn't matter.

Returns

Generator<Workspace, void, unknown>

load()

static load(projectRoot, options): Monorepo

Defined in: index.ts:858

Convenience method to instantiate and load in one call. Throws if called on a directory that is not a workspaces root.

Parameters

Returns

Monorepo

maybeLoad()

static maybeLoad(projectRoot, options): undefined | Monorepo

Defined in: index.ts:837

Convenience method to instantiate and load in one call. Returns undefined if the project is not a monorepo workspaces root, meaning none of vlt.json, the root package.json or pnpm-workspace.yaml declares any workspaces. Otherwise returns the loaded Monorepo.

Parameters

Returns

undefined | Monorepo

Workspace

Defined in: index.ts:872

Class representing a single Workspace in a Monorepo

Constructors

new Workspace()

new Workspace(
   path, 
   manifest, 
   fullpath): Workspace

Defined in: index.ts:881

Parameters

Returns

Workspace

Properties

Accessors

keys

Get Signature

get keys(): string[]

Defined in: index.ts:894

Returns

string[]

Type Aliases

LoadQuery

type LoadQuery = object;

Defined in: index.ts:46

The object passed to the constructor or Monorepo#load to limit which Workspaces get loaded.

Type declaration

MonorepoOptions

type MonorepoOptions = object;

Defined in: index.ts:277

Type declaration

ResolvedWorkspaceConfig

type ResolvedWorkspaceConfig = object;

Defined in: index.ts:200

Type declaration

WorkspaceConfig

type WorkspaceConfig = 
  | string[]
  | WorkspaceConfigObject
  | string;

Defined in: index.ts:68

Allowed datatype in the workspaces field of the vlt.json file.

WorkspaceConfigObject

type WorkspaceConfigObject = Record<string, string[]>;

Defined in: index.ts:63

Canonical form of the WorkspaceConfig, used internally for consistency.

WorkspaceConfigSource

type WorkspaceConfigSource = "vlt.json" | "package.json" | "pnpm-workspace.yaml";

Defined in: index.ts:197

Which file a project's workspace definitions came from.

WorkspacesLoadedConfig

type WorkspacesLoadedConfig = object;

Defined in: index.ts:37

Type declaration

Variables

workspaceCache

const workspaceCache: Map<string, Workspace>;

Defined in: index.ts:867

Functions

asManifestWSConfig()

function asManifestWSConfig(conf, path): WorkspaceConfigObject

Defined in: index.ts:168

Turn the workspaces field of a root package.json into a WorkspaceConfigObject.

Only the shapes npm and yarn-classic actually understand are accepted: a glob string, an array of them, or {packages: [...]}. vlt's named workspace groups are deliberately not accepted here -- a package.json using them would be meaningless to every other package manager, so they have to live in vlt.json.

Parameters

Returns

WorkspaceConfigObject

assertWSConfig()

function assertWSConfig(conf, path?): asserts conf is WorkspaceConfig

Defined in: index.ts:95

Throw if the provided value is not a valid WorkspaceConfig

Parameters

Returns

asserts conf is WorkspaceConfig

asWSConfig()

function asWSConfig(conf, path?): WorkspaceConfigObject

Defined in: index.ts:75

Turn a WorkspaceConfig into a WorkspaceConfigObject, or throw if it's not valid.

Parameters

Returns

WorkspaceConfigObject

resolveWSConfig()

function resolveWSConfig(projectRoot, packageJson): ResolvedWorkspaceConfig

Defined in: index.ts:220

Resolve the effective workspace definitions for a project.

vlt.json wins whenever it has a workspaces field; otherwise the npm/yarn-style workspaces field of the project root's package.json is used, then the packages list of a root pnpm-workspace.yaml. Note the precedence is keyed on the field, not the file: a vlt.json that exists but says nothing about workspaces still falls through to package.json.

Parameters

Returns

ResolvedWorkspaceConfig

splitNegatedPatterns()

function splitNegatedPatterns(all): object

Defined in: index.ts:256

Split a list of glob patterns into the positive patterns and the npm-compatible !-negated ones, which become ignore patterns.

Follows npm's map-workspaces rules: an even number of leading ! is a positive pattern (!!foo means foo), a leading ./ or / is stripped, and a later positive pattern un-negates any earlier negation it matches, so ['a/**', '!a/b/**', 'a/b/c'] keeps a/b/c.

Parameters

Returns

object