workspace-root

library3.3.1jsnpmunverified

The `workspace-root` package provides a robust utility for programmatically identifying the root directory of a monorepo workspace. It supports various popular package managers and monorepo tools including Yarn, pnpm, Lerna, and Bun. The library exposes both synchronous (`workspaceRootSync`) and asynchronous (`workspaceRoot`) functions, allowing developers to choose the appropriate API for their context, with an optional `cwd` parameter to specify the starting search path. Currently stable at version 3.3.1, the package demonstrates a consistent release cadence with frequent minor updates and patches, and underwent a significant architectural refactor in version 3.0.0. Its primary differentiator is its broad compatibility across different monorepo configurations and package manager specifics, such as Yarn's `nohoist` option, ensuring accurate root detection even in complex setups.

devops

npm install workspace-root

github ↗package ↗

INSTALL

IMPORT

SIG · WORKSPACE-ROOT

workspace-root

devopsjavascriptv3.3.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

workspaceRoot

✓ import { workspaceRoot } from 'workspace-root'

✗ const workspaceRoot = require('workspace-root')

While CommonJS `require` is supported, prefer ESM `import` for modern Node.js applications. This function returns a Promise.

workspaceRootSync

✓ import { workspaceRootSync } from 'workspace-root'

✗ const { workspaceRootSync } = require('workspace-root')

This function provides a synchronous API for immediate root detection. Like `workspaceRoot`, CommonJS `require` is also supported.

WorkspaceRootTypes

✓ import type { WorkspaceRootResult } from 'workspace-root'

The package ships with TypeScript types. The primary type for the return value of the root functions is typically `string | null`.

Demonstrates both asynchronous and synchronous methods of finding the workspace root, including specifying a custom current working directory.

import { workspaceRoot, workspaceRootSync } from 'workspace-root'; // Asynchronous usage async function findAsyncRoot() { const path = await workspaceRoot(); if (path) { console.log('The workspace root (async) is: ', path); } else { console.log('No workspace root found (async).'); } } findAsyncRoot(); // Synchronous usage const syncPath = workspaceRootSync(); if (syncPath) { console.log('The workspace root (sync) is: ', syncPath); } else { console.log('No workspace root found (sync).'); } // Example with custom current working directory // For demonstration, let's assume '/tmp' exists and you want to search from there. // In a real scenario, you'd pass a path relevant to your project structure. const customCwd = process.env.TEMP || '/tmp'; // Use a temporary directory for example console.log(`Searching from custom CWD: ${customCwd}`); workspaceRoot(customCwd).then(path => { console.log(`The workspace root from ${customCwd} (async) is: `, path); }); console.log(`The workspace root from ${customCwd} (sync) is: `, workspaceRootSync(customCwd));

Debug

Known issues

breakingVersion 3.0.0 introduced significant internal changes to the build process, including using esbuild and new output formats. While core API (`workspaceRoot`, `workspaceRootSync`) remained stable, consumers relying on specific module resolutions, bundler configurations, or deeply internal package structure might require adjustments.

fix

Review your build pipeline and module resolution configurations, especially if you encountered issues after upgrading from a pre-3.0.0 version. Ensure your bundler (e.g., Webpack, Rollup) correctly resolves ESM and CJS outputs.

affects: >=3.0.0

gotchaPrior to version 3.3.0, the utility might not have correctly identified the workspace root in monorepos utilizing Yarn's `workspaces.nohoist` feature, potentially returning `null` or an incorrect path.

fix

Upgrade to `workspace-root@3.3.0` or higher to ensure proper compatibility with `yarn workspaces.nohoist` configurations.

affects: <3.3.0

gotchaThe `workspaceRoot` function returns a Promise. Forgetting to `await` its result or chain with `.then()` will lead to handling a Promise object directly instead of the resolved path.

fix

Always `await workspaceRoot()` in an `async` function or use `workspaceRoot().then(path => { ... })` to correctly retrieve the workspace path.

affects: >=1.0.0

gotchaWhile `workspace-root` aims for broad compatibility, complex or non-standard monorepo setups (e.g., deeply nested workspaces, custom `package.json` structures, specific `pnpm` or `yarn` configurations outside conventional patterns) might occasionally result in `null` being returned.

fix

When `null` is returned unexpectedly, verify your monorepo's `package.json` `workspaces` configuration and `pnpm-workspace.yaml` (if applicable) adheres to standard conventions. Consider providing an explicit `cwd` parameter to narrow the search scope if the issue persists.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'workspace-root'

The package is not installed, or the Node.js module resolution path is incorrect.

fix

Ensure the package is installed: `npm install workspace-root`, `yarn add workspace-root`, or `pnpm add workspace-root`. Check your `node_modules` directory and `NODE_PATH` environment variable if running in a non-standard environment.

TypeError: workspaceRoot is not a function

Incorrect import statement or attempting to destructure a CommonJS `require` call in a context expecting a different module format (e.g., mixing `import { workspaceRoot } from 'workspace-root'` with `require('workspace-root').default`).

fix

For ESM, use `import { workspaceRoot } from 'workspace-root';`. For CJS, use `const { workspaceRoot } = require('workspace-root');`. Ensure you are destructuring correctly based on the module type.

Promise { <pending> }

The asynchronous `workspaceRoot()` function was called, but its Promise return value was not handled with `await` or `.then()`.

fix

To get the resolved value, `await` the function call within an `async` context: `const path = await workspaceRoot();` or use a Promise callback: `workspaceRoot().then(path => console.log(path));`.

Upgrade

Version history

3.3.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/saqqdy/node-kit ↗

packagehttps://www.npmjs.com/package/workspace-root ↗