0
# @pnpm/find-workspace-dir
1

2
@pnpm/find-workspace-dir is a utility library that finds the root directory of a pnpm workspace by searching for `pnpm-workspace.yaml` files. It supports environment variable overrides and handles case-insensitive file systems correctly.
3

4
## Package Information
5

6
- **Package Name**: @pnpm/find-workspace-dir
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `pnpm add @pnpm/find-workspace-dir`
10

11
## Core Imports
12

13
```typescript
14
import { findWorkspaceDir } from "@pnpm/find-workspace-dir";
15
import { PnpmError } from "@pnpm/error";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { findWorkspaceDir } = require("@pnpm/find-workspace-dir");
22
const { PnpmError } = require("@pnpm/error");
23
```
24

25
## Basic Usage
26

27
```typescript
28
import { findWorkspaceDir } from "@pnpm/find-workspace-dir";
29

30
// Find workspace directory from current working directory
31
const workspaceDir = await findWorkspaceDir(process.cwd());
32

33
if (workspaceDir) {
34
  console.log(`Found workspace at: ${workspaceDir}`);
35
} else {
36
  console.log("No workspace found");
37
}
38

39
// Find workspace directory from a specific path
40
const workspaceDir2 = await findWorkspaceDir("/path/to/project");
41
```
42

43
## Capabilities
44

45
### Workspace Directory Discovery
46

47
Finds the root directory of a pnpm workspace by searching for `pnpm-workspace.yaml` files in the current directory and parent directories.
48

49
```typescript { .api }
50
/**
51
 * Finds the root directory of a pnpm workspace by searching for pnpm-workspace.yaml files
52
 * @param cwd - Current working directory to start searching from
53
 * @returns Promise resolving to workspace directory path or undefined if not found
54
 * @throws PnpmError with code 'ERR_PNPM_BAD_WORKSPACE_MANIFEST_NAME' if invalid workspace manifest filename is found
55
 */
56
function findWorkspaceDir(cwd: string): Promise<string | undefined>;
57
```
58

59
**Behavior:**
60

61
- Searches for `pnpm-workspace.yaml` files starting from the provided directory and moving up the directory tree
62
- Respects the `NPM_CONFIG_WORKSPACE_DIR` (or `npm_config_workspace_dir`) environment variable for workspace directory override
63
- Handles case-insensitive file systems by resolving real native paths
64
- Throws an error if invalid workspace manifest filenames are detected (`pnpm-workspaces.yaml`, `pnpm-workspaces.yml`, `pnpm-workspace.yml`)
65

66
**Usage Examples:**
67

68
```typescript
69
import { findWorkspaceDir } from "@pnpm/find-workspace-dir";
70
import { PnpmError } from "@pnpm/error";
71

72
// Basic usage
73
try {
74
  const workspaceDir = await findWorkspaceDir(process.cwd());
75
  if (workspaceDir) {
76
    console.log(`Workspace found at: ${workspaceDir}`);
77
  } else {
78
    console.log("No pnpm workspace found");
79
  }
80
} catch (error) {
81
  if (error instanceof PnpmError && error.code === 'ERR_PNPM_BAD_WORKSPACE_MANIFEST_NAME') {
82
    console.error('Invalid workspace manifest filename:', error.message);
83
  }
84
}
85

86
// Using environment variable override
87
process.env.NPM_CONFIG_WORKSPACE_DIR = '/custom/workspace/path';
88
const workspaceDir = await findWorkspaceDir(process.cwd());
89
// Returns '/custom/workspace/path' regardless of cwd
90
```
91

92
## Error Handling
93

94
The function throws a `PnpmError` when invalid workspace manifest filenames are detected:
95

96
```typescript { .api }
97
class PnpmError extends Error {
98
  readonly code: string;
99
  readonly hint?: string;
100
  attempts?: number;
101
  prefix?: string;
102
  pkgsStack?: Array<{ id: string, name: string, version: string }>;
103
  
104
  constructor(
105
    code: string,
106
    message: string,
107
    opts?: {
108
      attempts?: number;
109
      hint?: string;
110
    }
111
  );
112
}
113
```
114

115
**Error Codes:**
116

117
- `ERR_PNPM_BAD_WORKSPACE_MANIFEST_NAME`: Thrown when an invalid workspace manifest filename is found (e.g., `pnpm-workspaces.yaml` instead of `pnpm-workspace.yaml`)
118

119
## Environment Variables
120

121
**NPM_CONFIG_WORKSPACE_DIR** / **npm_config_workspace_dir**
122

123
When set, either of these environment variables overrides the workspace directory search and directly returns the specified path. The function appends `pnpm-workspace.yaml` to this path as the workspace manifest location. The function checks both `NPM_CONFIG_WORKSPACE_DIR` and `npm_config_workspace_dir` (the lowercase variant).
124

125
```bash
126
# Override workspace directory (either format works)
127
export NPM_CONFIG_WORKSPACE_DIR="/path/to/workspace"
128
# or
129
export npm_config_workspace_dir="/path/to/workspace"
130
```
131

132
## Node.js Compatibility
133

134
- **Minimum Node.js Version**: 18.12
135
- **Module Type**: CommonJS
136
- **TypeScript Support**: Full type definitions included