{"id":12676,"library":"workspace-root","title":"Workspace Root Detector","description":"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.","status":"active","version":"3.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/saqqdy/node-kit","tags":["javascript","node-kit","workspace","lerna-workspace","pnpm-workspace","yarn-workspace","workspace-root","typescript"],"install":[{"cmd":"npm install workspace-root","lang":"bash","label":"npm"},{"cmd":"yarn add workspace-root","lang":"bash","label":"yarn"},{"cmd":"pnpm add workspace-root","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` is supported, prefer ESM `import` for modern Node.js applications. This function returns a Promise.","wrong":"const workspaceRoot = require('workspace-root')","symbol":"workspaceRoot","correct":"import { workspaceRoot } from 'workspace-root'"},{"note":"This function provides a synchronous API for immediate root detection. Like `workspaceRoot`, CommonJS `require` is also supported.","wrong":"const { workspaceRootSync } = require('workspace-root')","symbol":"workspaceRootSync","correct":"import { workspaceRootSync } from 'workspace-root'"},{"note":"The package ships with TypeScript types. The primary type for the return value of the root functions is typically `string | null`.","symbol":"WorkspaceRootTypes","correct":"import type { WorkspaceRootResult } from 'workspace-root'"}],"quickstart":{"code":"import { workspaceRoot, workspaceRootSync } from 'workspace-root';\n\n// Asynchronous usage\nasync function findAsyncRoot() {\n  const path = await workspaceRoot();\n  if (path) {\n    console.log('The workspace root (async) is: ', path);\n  } else {\n    console.log('No workspace root found (async).');\n  }\n}\n\nfindAsyncRoot();\n\n// Synchronous usage\nconst syncPath = workspaceRootSync();\nif (syncPath) {\n  console.log('The workspace root (sync) is: ', syncPath);\n} else {\n  console.log('No workspace root found (sync).');\n}\n\n// Example with custom current working directory\n// For demonstration, let's assume '/tmp' exists and you want to search from there.\n// In a real scenario, you'd pass a path relevant to your project structure.\nconst customCwd = process.env.TEMP || '/tmp'; // Use a temporary directory for example\nconsole.log(`Searching from custom CWD: ${customCwd}`);\n\nworkspaceRoot(customCwd).then(path => {\n  console.log(`The workspace root from ${customCwd} (async) is: `, path);\n});\n\nconsole.log(`The workspace root from ${customCwd} (sync) is: `, workspaceRootSync(customCwd));","lang":"typescript","description":"Demonstrates both asynchronous and synchronous methods of finding the workspace root, including specifying a custom current working directory."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade to `workspace-root@3.3.0` or higher to ensure proper compatibility with `yarn workspaces.nohoist` configurations.","message":"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.","severity":"gotcha","affected_versions":"<3.3.0"},{"fix":"Always `await workspaceRoot()` in an `async` function or use `workspaceRoot().then(path => { ... })` to correctly retrieve the workspace path.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The package is not installed, or the Node.js module resolution path is incorrect.","error":"Error: Cannot find module 'workspace-root'"},{"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.","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`).","error":"TypeError: workspaceRoot is not a function"},{"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));`.","cause":"The asynchronous `workspaceRoot()` function was called, but its Promise return value was not handled with `await` or `.then()`.","error":"Promise { <pending> }"}],"ecosystem":"npm"}