workspace-version-resolver

A small Node.js library and CLI that resolves workspace protocol versions in a monorepo. It reads each workspace package’s package.json, finds dependencies that use the workspace: protocol (e.g. workspace:*, workspace:^), replaces them with the actual package versions, and writes the changes back without reordering or reformatting the rest of the file.

Useful for pre-publish steps or tooling that needs concrete versions instead of workspace:* in dependency maps.

Table of contents

• Installation
• Quick start
• CLI
• Programmatic API
• How it works
• Version resolution rules
• Requirements and behavior
• License

Installation

npm install workspace-version-resolver
# or
pnpm add workspace-version-resolver
# or
bun add workspace-version-resolver

Quick start

CLI — run from the monorepo root (or pass a path). The binary is also available under the alias wvr:

npx workspace-version-resolver
# or
npx workspace-version-resolver /path/to/monorepo

API — call the default export with the root directory:

import resolveWorkspaceVersions from 'workspace-version-resolver';

await resolveWorkspaceVersions('/path/to/monorepo');

CLI

The package ships a binary: workspace-version-resolver (alias wvr). Run via npx, bunx, or after npm install -g.

Usage

workspace-version-resolver [path]

• [path] — Optional path to the monorepo root. If omitted, the current working directory is used.

Options

| Option | Alias | Type | Default | Description | |--------|--------|------|---------|-------------| | --warn-on-circular | — | boolean | true | When true, print a warning for each circular workspace dependency. Use --no-warn-on-circular to disable. | | --help | -h | boolean | — | Show help and exit. | | --version | -v | boolean | — | Show package version and exit. |

Examples

# Use current directory as monorepo root
npx workspace-version-resolver

# Explicit path
npx workspace-version-resolver path/to/monorepo/

# Disable circular dependency warnings
npx workspace-version-resolver --no-warn-on-circular

# Help and version
npx workspace-version-resolver --help
npx workspace-version-resolver --version

On validation or runtime errors, the process exits with code 1 and prints the error message to stderr.

Programmatic API

The package exports a default function and the individual steps + types so you can reuse or test them.

Default export: resolveWorkspaceVersions

Runs the full pipeline: validate root → resolve workspace paths → read manifests → build graph → topological sort → resolve versions → write package.json files.

function resolveWorkspaceVersions(
  rootDir: string,
  options?: ResolveWorkspaceVersionsOptions
): Promise<void>

• rootDir — Absolute or relative path to the monorepo root (directory that contains a package.json with a "workspaces" array).
• options — Optional:
  • warnOnCircular?: boolean — If true (default), console.warn is used when circular workspace dependencies are detected. Does not throw.

Example

import resolveWorkspaceVersions from 'workspace-version-resolver';

await resolveWorkspaceVersions(process.cwd(), { warnOnCircular: true });

Options type

interface ResolveWorkspaceVersionsOptions {
  /** If true (default), emit console.warn when circular dependencies are detected. */
  warnOnCircular?: boolean;
}

Named exports (modular steps)

You can call each step yourself for custom workflows or tests.

| Export | Description | |--------|-------------| | validateRoot(rootDir: string) | Ensures rootDir is a directory and has a package.json with a "workspaces" array of strings. Returns { workspaces: string[] }. Throws on invalid root. | | resolveWorkspacePaths(rootPath, workspaces) | Expands workspace globs (e.g. packages/*) to absolute directory paths and keeps only directories that contain a package.json. Returns string[]. | | readManifests(dirPaths) | Reads each directory’s package.json, extracts name, version, dependencies, devDependencies, peerDependencies, and workspace-only deps. Returns PackageInfo[]. Throws on duplicate package names. | | buildDependencyGraph(packages) | Builds a directed graph of workspace packages (by name, edges = “depends on”). Returns DependencyGraph. | | topologicalSort(graph) | Returns a topological order (packages with no workspace deps first) and any cycles found. Returns TopoResult ({ ordered: string[], cycles: string[][] }). Does not throw on cycles. | | resolveVersions(ordered, packages) | Resolves each workspace specifier to the depended-on package’s version. Returns ResolvedUpdates ({ byPackage: Map<string, Map<string, string>> }). | | resolveVersionSpec(specifier, targetVersion) | Resolves a single specifier string (e.g. "workspace:*") given the target package version. Returns the resolved version string. | | writePackageJson(dirPath, updates, workspaceDeps) | Writes back only the resolved version values into the given directory’s package.json, preserving formatting and key order. |

Types

type DependencyMap = Record<string, string>;

interface PackageInfo {
  dirPath: string;
  name: string;
  version: string;
  dependencies: DependencyMap;
  devDependencies: DependencyMap;
  peerDependencies: DependencyMap;
  workspaceDeps: DependencyMap;  // workspace: entries only
}

type DependencyGraph = Map<string, Set<string>>;

interface TopoResult {
  ordered: string[];
  cycles: string[][];
}

Example: custom pipeline

import path from 'node:path';
import {
  validateRoot,
  resolveWorkspacePaths,
  readManifests,
  buildDependencyGraph,
  topologicalSort,
  resolveVersions,
  writePackageJson,
} from 'workspace-version-resolver';

const rootDir = path.resolve('./my-monorepo');
const { workspaces } = validateRoot(rootDir);
const dirPaths = resolveWorkspacePaths(rootDir, workspaces);
const packages = readManifests(dirPaths);
const graph = buildDependencyGraph(packages);
const { ordered, cycles } = topologicalSort(graph);
if (cycles.length > 0) console.warn('Cycles:', cycles);
const { byPackage } = resolveVersions(ordered, packages);
for (const pkg of packages) {
  const updates = byPackage.get(pkg.dirPath);
  if (updates?.size) writePackageJson(pkg.dirPath, updates, pkg.workspaceDeps);
}

How it works

1. Validate root — Checks that rootDir is a directory and that its package.json has a "workspaces" array of strings.
2. Resolve workspace paths — Expands each workspace entry (e.g. packages/*) to absolute directory paths and keeps only directories that contain a package.json.
3. Read manifests — Reads each package’s package.json and extracts name, version, dependencies, devDependencies, and peerDependencies. Duplicate package names cause an error.
4. Workspace deps — From each manifest, only entries whose value starts with workspace: are considered (e.g. workspace:*, workspace:^, workspace:~, workspace:1.2.3).
5. Dependency graph — Builds a directed graph of packages based only on workspace dependencies.
6. Topological sort — Orders packages so that those with no workspace deps come first, then their dependents. Cycles are detected and reported (warning only, no throw).
7. Resolve versions — For each workspace dependency, computes the resolved version string from the depended-on package’s version and the specifier (see Version resolution rules).
8. Write back — Updates each package.json by replacing only the workspace:... values with the resolved versions, using a surgical string replace so that key order and formatting are preserved.

Version resolution rules

For each dependency that uses the workspace: protocol, the resolved value is derived from the depended-on package’s version and the specifier:

| Specifier | Resolved value | Example (target version 1.2.3) | |-----------|----------------|----------------------------------| | workspace:* | Exact version | 1.2.3 | | workspace:^ | Caret + version | ^1.2.3 | | workspace:~ | Tilde + version | ~1.2.3 | | workspace:1.2.3 | Strip workspace: | 1.2.3 | | workspace:^1.2.3 | Strip workspace: | ^1.2.3 | | workspace:~1.0.0 | Strip workspace: | ~1.0.0 |

Only dependency entries whose value is a string starting with workspace: are modified; all other keys and values are left unchanged.

Requirements and behavior

• Root must be a directory whose package.json contains a "workspaces" property set to an array of strings (e.g. ["packages/*"]).
• Workspace entries are resolved relative to the root and expanded (e.g. globs). Only directories that contain a package.json are included.
• Duplicate package names (same name in more than one workspace package) cause the run to throw (or the CLI to exit with code 1).
• Circular workspace dependencies are detected and reported with a warning only; the run continues and versions are still resolved where possible.
• File writes change only the version strings for workspace-resolved dependencies; property order and formatting (whitespace, newlines) are preserved.

License

MIT. See LICENSE in the repository.

Made with ❤️ by Lacus Solutions