{"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,"search_vec":"'3.0.0':95 '3.3.1':73 'accur':118 'across':103 'allow':48 'api':54 'appropri':53 'architectur':91 'asynchron':45 'broad':101 'bun':37 'cadenc':80 'choos':51 'compat':102 'complex':123 'configur':106 'consist':78 'context':57 'current':69 'cwd':61 'demonstr':76 'detect':120 'detector':3 'develop':49 'differ':104 'differenti':98 'directori':18 'ensur':117 'even':121 'expos':40 'frequent':82 'function':47 'identifi':15 'includ':32 'javascript':125 'kit':128 'lerna':35,131 'lerna-workspac':130 'librari':39 'manag':28,109 'minor':83 'monorepo':21,30,105 'node':127 'node-kit':126 'nohoist':115 'option':60,116 'packag':8,27,75,108 'paramet':62 'patch':86 'path':68 'pnpm':34,134 'pnpm-workspac':133 'popular':26 'primari':97 'programmat':14 'provid':9 'refactor':92 'releas':79 'robust':11 'root':2,7,17,119,141 'search':67 'setup':124 'signific':90 'specif':110 'specifi':64 'stabl':70 'start':66 'support':24 'synchron':42 'tool':31 'typescript':142 'underw':88 'updat':84 'util':12 'various':25 'version':72,94 'workspac':1,6,22,129,132,135,138,140 'workspace-root':5,139 'workspaceroot':46 'workspacerootsync':43 'yarn':33,113,137 'yarn-workspac':136","created_at":"2026-04-19T13:44:24.718612+00:00","updated_at":"2026-04-19T13:44:24.718612+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/saqqdy/node-kit","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/workspace-root","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}