0
# Configuration and Environment
1

2
Configure pnpm settings, manage Node.js environments, and set up shell integrations for optimal development workflows.
3

4
## Capabilities
5

6
### Configuration Management
7

8
Manage pnpm configuration settings through CLI commands and configuration files.
9

10
```bash { .api }
11
/**
12
 * Manage pnpm configuration settings
13
 * Supports global, user, and project-level configuration
14
 */
15
pnpm config <command> [options]
16
pnpm c <command> [options]
17
```
18

19
**Available Commands:**
20
- `get <key>` - Get configuration value
21
- `set <key> <value>` - Set configuration value
22
- `delete <key>` - Delete configuration key
23
- `list` - List all configuration
24
- `edit` - Edit configuration file
25

26
**Usage Examples:**
27

28
```bash
29
# List all configuration
30
pnpm config list
31

32
# Get specific setting
33
pnpm config get registry
34

35
# Set configuration value
36
pnpm config set registry https://registry.npmjs.org
37

38
# Delete configuration
39
pnpm config delete proxy
40

41
# Edit configuration file
42
pnpm config edit
43
```
44

45
### Get Configuration Values
46

47
Retrieve specific configuration values or display current settings.
48

49
```bash { .api }
50
/**
51
 * Get configuration values
52
 * Retrieves settings from config hierarchy
53
 */
54
pnpm get <key> [options]
55
```
56

57
**Usage Examples:**
58

59
```bash
60
# Get registry URL
61
pnpm get registry
62

63
# Get store directory
64
pnpm get store-dir
65

66
# Get all settings (same as config list)
67
pnpm get
68
```
69

70
### Set Configuration Values
71

72
Set configuration values at different scopes (global, user, project).
73

74
```bash { .api }
75
/**
76
 * Set configuration values
77
 * Updates configuration files with new values
78
 */
79
pnpm set <key> <value> [options]
80
```
81

82
**Options:**
83
- `--global`, `-g` - Set in global config
84
- `--location <location>` - Set in specific config location
85

86
**Usage Examples:**
87

88
```bash
89
# Set registry
90
pnpm set registry https://npm.example.com
91

92
# Set global configuration
93
pnpm set --global store-dir /shared/pnpm-store
94

95
# Set package manager settings
96
pnpm set auto-install-peers true
97
pnpm set strict-peer-dependencies false
98
```
99

100
## Configuration Files
101

102
### Configuration Hierarchy
103

104
pnpm reads configuration from multiple sources in priority order:
105

106
```bash { .api }
107
# Configuration priority (highest to lowest)
108
1. Command line options          # --registry=...
109
2. Environment variables         # PNPM_REGISTRY=...
110
3. Project .pnpmrc              # ./pnpmrc or ./.pnpmrc
111
4. Workspace .pnpmrc            # <workspace-root>/.pnpmrc
112
5. User .pnpmrc                 # ~/.pnpmrc
113
6. Global .pnpmrc               # /etc/pnpmrc
114
7. Default values               # Built-in defaults
115
```
116

117
### .pnpmrc File Format
118

119
Configuration file syntax and common settings:
120

121
```ini { .api }
122
# Registry configuration
123
registry=https://registry.npmjs.org
124
@myorg:registry=https://npm.myorg.com
125

126
# Store configuration  
127
store-dir=~/.pnpm-store
128
package-import-method=hardlink
129

130
# Installation behavior
131
auto-install-peers=true
132
strict-peer-dependencies=false
133
shamefully-hoist=false
134

135
# Workspace settings
136
link-workspace-packages=true
137
shared-workspace-lockfile=true
138

139
# Logging and output
140
loglevel=info
141
reporter=default
142

143
# Network settings
144
fetch-retries=3
145
fetch-retry-factor=2
146
fetch-timeout=60000
147

148
# Security settings
149
audit-level=moderate
150
```
151

152
### Common Configuration Options
153

154
Key configuration settings and their usage:
155

156
```bash { .api }
157
# Package management
158
auto-install-peers              # Automatically install peer dependencies
159
strict-peer-dependencies        # Fail on missing peer dependencies  
160
shamefully-hoist               # Hoist dependencies (not recommended)
161
public-hoist-pattern           # Patterns for public hoisting
162

163
# Store and caching
164
store-dir                      # Global store directory
165
cache-dir                      # Cache directory
166
package-import-method          # hardlink, copy, or clone
167
verify-store-integrity         # Verify packages when adding to store
168

169
# Lockfile behavior
170
lockfile                       # Generate lockfile (default: true)
171
lockfile-dir                   # Lockfile directory
172
frozen-lockfile               # Don't update lockfile
173
prefer-frozen-lockfile        # Prefer existing lockfile
174

175
# Registry and network
176
registry                      # Default registry URL
177
fetch-retries                 # Network retry attempts
178
fetch-timeout                 # Network timeout (ms)
179
ca                           # Certificate authority
180
cert                         # Client certificate
181
key                          # Client key
182

183
# Workspace configuration
184
link-workspace-packages       # Link workspace packages
185
shared-workspace-lockfile     # Single lockfile for workspace
186
```
187

188
## Environment Management
189

190
### Node.js Version Management
191

192
Manage Node.js versions per project with integrated version switching.
193

194
```bash { .api }
195
/**
196
 * Manage Node.js environments and versions
197
 * Provides Node.js version management similar to nvm
198
 */
199
pnpm env <command> [options]
200
```
201

202
**Available Commands:**
203
- `use <version>` - Use specific Node.js version
204
- `list` - List installed Node.js versions
205
- `list-remote` - List available remote versions
206
- `install <version>` - Install Node.js version
207
- `remove <version>` - Remove Node.js version
208

209
**Usage Examples:**
210

211
```bash
212
# Install and use Node.js version
213
pnpm env use 18.17.0
214

215
# List installed versions
216
pnpm env list
217

218
# List available remote versions
219
pnpm env list-remote
220

221
# Install specific version
222
pnpm env install 20.5.0
223

224
# Remove version
225
pnpm env remove 16.20.0
226
```
227

228
### Project Node.js Version
229

230
Configure project-specific Node.js version requirements.
231

232
```json { .api }
233
// package.json - engine requirements
234
{
235
  "engines": {
236
    "node": ">=18.12.0"
237
  }
238
}
239

240
// .nvmrc - version specification
241
18.17.0
242
```
243

244
**Configuration Options:**
245
```bash { .api }
246
# Set Node.js version for project
247
pnpm config set use-node-version 18.17.0
248

249
# Environment variable
250
export PNPM_NODE_VERSION=18.17.0
251
```
252

253
### Environment Setup
254

255
Set up pnpm environment and shell integrations.
256

257
```bash { .api }
258
/**
259
 * Setup pnpm environment and shell integration
260
 * Configures PATH, completion, and shell hooks
261
 */
262
pnpm setup [options]
263
```
264

265
**Options:**
266
- `--shell <shell>` - Specify shell (bash, zsh, fish, powershell)
267
- `--global` - Set up globally
268

269
**Usage Examples:**
270

271
```bash
272
# Setup for current shell
273
pnpm setup
274

275
# Setup for specific shell
276
pnpm setup --shell zsh
277

278
# Global setup
279
pnpm setup --global
280
```
281

282
## System Information
283

284
### Binary Directory
285

286
Show the directory containing pnpm executables.
287

288
```bash { .api }
289
/**
290
 * Show path to executable directory
291
 * Returns directory containing pnpm binaries
292
 */
293
pnpm bin [options]
294
```
295

296
**Options:**
297
- `--global`, `-g` - Show global bin directory
298

299
**Usage Examples:**
300

301
```bash
302
# Show local bin directory
303
pnpm bin
304

305
# Show global bin directory
306
pnpm bin -g
307

308
# Use in scripts
309
export PATH="$(pnpm bin):$PATH"
310
```
311

312
### Modules Directory
313

314
Show the directory containing installed packages.
315

316
```bash { .api }
317
/**
318
 * Show path to modules directory
319
 * Returns directory containing node_modules
320
 */
321
pnpm root [options]
322
```
323

324
**Options:**
325
- `--global`, `-g` - Show global modules directory
326

327
**Usage Examples:**
328

329
```bash
330
# Show local modules directory
331
pnpm root
332

333
# Show global modules directory  
334
pnpm root -g
335

336
# Use in scripts
337
NODE_MODULES=$(pnpm root)
338
```
339

340
## Registry Configuration
341

342
### Multiple Registries
343

344
Configure different registries for different scopes:
345

346
```bash { .api }
347
# Set default registry
348
pnpm set registry https://registry.npmjs.org
349

350
# Set scoped registry
351
pnpm set @myorg:registry https://npm.myorg.com
352

353
# Set registry with authentication
354
pnpm set //npm.myorg.com:_authToken YOUR_TOKEN
355
```
356

357
### Registry Authentication
358

359
Configure authentication for private registries:
360

361
```bash { .api }
362
# Token-based authentication
363
//registry.npmjs.org/:_authToken=npm_TOKEN
364

365
# Username/password authentication
366
//npm.myorg.com/:username=myuser
367
//npm.myorg.com/:_password=BASE64_PASSWORD
368
//npm.myorg.com/:email=user@myorg.com
369

370
# Certificate-based authentication
371
ca=/path/to/ca.pem
372
cert=/path/to/cert.pem
373
key=/path/to/key.pem
374
```
375

376
## Performance Configuration
377

378
### Network Settings
379

380
Configure network behavior for optimal performance:
381

382
```bash { .api }
383
# Network timeouts and retries
384
fetch-timeout=60000           # Request timeout in milliseconds
385
fetch-retries=3              # Number of retry attempts
386
fetch-retry-factor=2         # Retry delay multiplier
387
fetch-retry-mintimeout=1000  # Minimum retry delay
388
fetch-retry-maxtimeout=60000 # Maximum retry delay
389

390
# Concurrent connections
391
network-concurrency=16       # Max concurrent network requests
392
```
393

394
### Cache Configuration
395

396
Configure caching behavior:
397

398
```bash { .api }
399
# Cache settings
400
cache-dir=~/.pnpm-cache       # Cache directory
401
cache-max=Infinity           # Maximum cache size
402
cache-min=0                  # Minimum cache retention time
403

404
# Offline behavior
405
prefer-offline=false         # Prefer cached packages
406
offline=false               # Work offline only
407
```
408

409
## Security Configuration
410

411
### Audit Settings
412

413
Configure security audit behavior:
414

415
```bash { .api }
416
# Audit configuration
417
audit-level=moderate         # Audit severity level (low, moderate, high, critical)
418
audit=true                  # Enable audit on install
419

420
# Package verification
421
verify-store-integrity=true  # Verify package integrity
422
```
423

424
### Package Manager Enforcement
425

426
Enforce specific package manager usage:
427

428
```json { .api }
429
// package.json - enforce pnpm usage
430
{
431
  "packageManager": "pnpm@8.6.12",
432
  "engines": {
433
    "pnpm": ">=8.0.0"
434
  }
435
}
436
```
437

438
**Configuration:**
439
```bash { .api }
440
# Package manager settings
441
package-manager-strict=true        # Enforce packageManager field
442
package-manager-strict-version=true # Enforce exact version
443
```
444

445
## Self-Management
446

447
### Self-Update
448

449
Update pnpm to the latest version.
450

451
```bash { .api }
452
/**
453
 * Update pnpm to latest version
454
 * Downloads and installs the latest pnpm release
455
 */
456
pnpm self-update [options]
457
```
458

459
**Usage Examples:**
460

461
```bash
462
# Update to latest version
463
pnpm self-update
464

465
# Update to specific version
466
pnpm self-update 8.7.0
467
```
468

469
### Shell Completion
470

471
Generate shell completion scripts for enhanced CLI experience.
472

473
```bash { .api }
474
/**
475
 * Generate shell completion script
476
 * Enables tab completion for pnpm commands
477
 */
478
pnpm completion [shell] [options]
479
```
480

481
**Supported Shells:**
482
- `bash` - Bash completion
483
- `zsh` - Zsh completion  
484
- `fish` - Fish completion
485
- `powershell` - PowerShell completion
486

487
**Usage Examples:**
488

489
```bash
490
# Generate completion for current shell
491
pnpm completion
492

493
# Generate completion for specific shell
494
pnpm completion bash > ~/.pnpm-completion.bash
495

496
# Install completion for zsh
497
pnpm completion zsh > ~/.zsh/completions/_pnpm
498
```
499

500
### Project Initialization
501

502
Initialize new Node.js projects with package.json and basic configuration.
503

504
```bash { .api }
505
/**
506
 * Initialize new Node.js project
507
 * Creates package.json and basic project structure
508
 */
509
pnpm init [options]
510
```
511

512
**Options:**
513
- `--yes`, `-y` - Accept all defaults without prompting
514
- `--scope <scope>` - Initialize scoped package
515
- `--private` - Mark package as private
516

517
**Usage Examples:**
518

519
```bash
520
# Initialize new project interactively
521
pnpm init
522

523
# Initialize with defaults
524
pnpm init -y
525

526
# Initialize scoped package
527
pnpm init --scope @myorg
528

529
# Initialize private package
530
pnpm init --private
531
```
532

533
### System Diagnostics
534

535
Diagnose pnpm installation and configuration issues.
536

537
```bash { .api }
538
/**
539
 * Diagnose pnpm installation and configuration
540
 * Checks for common issues and provides recommendations
541
 */
542
pnpm doctor [options]
543
```
544

545
**Usage Examples:**
546

547
```bash
548
# Run full diagnostic check
549
pnpm doctor
550

551
# Check specific directory
552
pnpm doctor --dir /path/to/project
553
```
554

555
The doctor command checks:
556
- pnpm installation integrity
557
- Node.js version compatibility
558
- Store location and permissions
559
- Workspace configuration
560
- Registry connectivity
561
- Common configuration issues