0
# @pnpm/store-path
1

2
@pnpm/store-path provides intelligent store path resolution for pnpm package manager installations. It determines the optimal location for the pnpm store directory based on filesystem capabilities, project location, and system permissions, ensuring maximum performance through hard linking when possible.
3

4
## Package Information
5

6
- **Package Name**: @pnpm/store-path
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @pnpm/store-path`
10

11
## Core Imports
12

13
```typescript
14
import { getStorePath } from "@pnpm/store-path";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { getStorePath } = require("@pnpm/store-path");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { getStorePath } from "@pnpm/store-path";
27

28
// Resolve store path with explicit location
29
const storePath = getStorePath({
30
  pkgRoot: "/home/user/my-project",
31
  storePath: "/custom/pnpm-store",
32
  pnpmHomeDir: "/home/user/.local/share/pnpm"
33
});
34
// Returns: "/custom/pnpm-store/v10"
35

36
// Resolve optimal store path based on filesystem capabilities
37
const optimalPath = await getStorePath({
38
  pkgRoot: "/home/user/my-project", 
39
  pnpmHomeDir: "/home/user/.local/share/pnpm"
40
});
41
// Returns: Promise<string> - optimal location based on hard linking support
42
```
43

44
## Architecture
45

46
The store path resolution follows a three-tier strategy:
47

48
1. **Explicit Path**: When `storePath` is provided, use it directly (appending store version if needed)
49
2. **Home-relative Path**: For paths starting with `~/`, resolve relative to user home directory
50
3. **Filesystem Optimization**: Automatically determine optimal location based on hard linking capabilities:
51
   - Test linking between project location and potential store locations
52
   - Prefer pnpm home directory if linking works across filesystems
53
   - Fall back to filesystem root with `.pnpm-store` prefix if linking only works locally
54
   - Ultimate fallback to pnpm home directory if no linking is possible
55

56
## Capabilities
57

58
### Store Path Resolution
59

60
Intelligently resolves the optimal pnpm store path location based on filesystem capabilities and configuration options.
61

62
```typescript { .api }
63
/**
64
 * Resolves the optimal pnpm store path based on filesystem capabilities
65
 * @param options - Configuration options for store path resolution
66
 * @returns Store path string (sync) or Promise<string> (async when optimization needed)
67
 * @throws PnpmError with code 'NO_PNPM_HOME_DIR' when pnpmHomeDir is undefined and storePath not provided
68
 */
69
function getStorePath(options: GetStorePathOptions): string | Promise<string>;
70

71
interface GetStorePathOptions {
72
  /** Root directory of the package/project */
73
  pkgRoot: string;
74
  /** 
75
   * Optional explicit store path - can be absolute or home-relative (~/path)
76
   * When provided, skips filesystem optimization and uses this path directly
77
   */
78
  storePath?: string;
79
  /** 
80
   * Pnpm home directory for fallback store location
81
   * Required when storePath is not provided
82
   */
83
  pnpmHomeDir: string;
84
}
85
```
86

87
**Usage Examples:**
88

89
```typescript
90
import { getStorePath } from "@pnpm/store-path";
91

92
// Explicit absolute store path
93
const explicitPath = getStorePath({
94
  pkgRoot: "/home/user/project",
95
  storePath: "/var/cache/pnpm",
96
  pnpmHomeDir: "/home/user/.local/share/pnpm"
97
});
98
// Returns: "/var/cache/pnpm/v10" (synchronous)
99

100
// Home-relative store path
101
const homePath = getStorePath({
102
  pkgRoot: "/home/user/project", 
103
  storePath: "~/custom-store",
104
  pnpmHomeDir: "/home/user/.local/share/pnpm"
105
});
106
// Returns: "/home/user/custom-store/v10" (synchronous)
107

108
// Optimized store path (filesystem linking detection)
109
const optimizedPath = await getStorePath({
110
  pkgRoot: "/mnt/external/project",
111
  pnpmHomeDir: "/home/user/.local/share/pnpm"
112
});
113
// Returns: Promise<string> - optimal location after testing hard linking capabilities
114

115
// Error handling
116
try {
117
  getStorePath({
118
    pkgRoot: "/some/project",
119
    pnpmHomeDir: undefined // This will throw an error
120
  });
121
} catch (error) {
122
  console.log(error.code); // 'NO_PNPM_HOME_DIR'
123
}
124
```
125

126
## Error Handling
127

128
The package throws `PnpmError` instances from the `@pnpm/error` package:
129

130
```typescript { .api }
131
// Error thrown when pnpmHomeDir is not provided and storePath is undefined
132
interface PnpmError extends Error {
133
  code: 'NO_PNPM_HOME_DIR';
134
  message: 'The pnpm home directory is unknown. Cannot calculate the store directory location.';
135
}
136
```
137

138
## Constants
139

140
The package uses the `STORE_VERSION` constant from `@pnpm/constants`, which is currently `"v10"`. This version is automatically appended to store paths to maintain compatibility across pnpm versions.
141

142
## Platform Support
143

144
- **Node.js**: Requires Node.js >= 18.12
145
- **Cross-platform**: Handles both Unix (`~/`) and Windows (`~\\`) home directory notation
146
- **Filesystem agnostic**: Works with various filesystem types, optimizing based on hard linking support