Workspace Root Detector

Common errors

• Error: Cannot find module 'workspace-root'

  cause 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

  cause 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> }

  cause 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));`.

Warnings

• breaking Version 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.
• gotcha Prior 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.
• gotcha The `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.
• gotcha While `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.

Install

• npm install workspace-root npm
• yarn add workspace-root yarn
• pnpm add workspace-root pnpm

Imports

• workspaceRoot
  wrong:

  const workspaceRoot = require('workspace-root')

  correct:

  import { workspaceRoot } from 'workspace-root'

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

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

  correct:

  import { workspaceRootSync } from '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`.

Quickstart

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));