0
# Script Running and Execution
1

2
Execute package scripts, run packages without installing, and manage development workflows with pnpm's comprehensive script running capabilities.
3

4
## Capabilities
5

6
### Run Package Scripts
7

8
Execute scripts defined in package.json with full lifecycle support and environment setup.
9

10
```bash { .api }
11
/**
12
 * Run scripts defined in package.json
13
 * Executes with proper PATH setup and lifecycle hooks
14
 */
15
pnpm run <script> [options]
16
pnpm run-script <script> [options]
17
```
18

19
**Options:**
20
- `--recursive`, `-r` - Run script in all workspace packages
21
- `--filter <pattern>` - Run script in filtered packages
22
- `--parallel` - Run scripts in parallel across workspaces
23
- `--stream` - Stream output from parallel runs
24
- `--if-present` - Don't fail if script doesn't exist
25
- `--` - Pass remaining arguments to the script
26

27
**Usage Examples:**
28

29
```bash
30
# Run development server
31
pnpm run dev
32

33
# Run tests
34
pnpm run test
35

36
# Run script with arguments
37
pnpm run build -- --watch
38

39
# Run in all workspaces
40
pnpm run -r test
41

42
# Run in filtered packages
43
pnpm run --filter "@myorg/*" build
44

45
# Run tests in parallel
46
pnpm run -r --parallel test
47
```
48

49
### Execute Without Installing (dlx)
50

51
Download and execute packages without installing them globally, similar to npx but faster.
52

53
```bash { .api }
54
/**
55
 * Download and execute packages without installing
56
 * Equivalent to npx but uses pnpm's fast store
57
 */
58
pnpm dlx <pkg> [args]
59
```
60

61
**Usage Examples:**
62

63
```bash
64
# Create React app
65
pnpm dlx create-react-app my-app
66

67
# Run TypeScript compiler
68
pnpm dlx tsc --version
69

70
# Execute with specific version
71
pnpm dlx create-next-app@latest my-next-app
72

73
# Execute with arguments
74
pnpm dlx eslint src/ --fix
75
```
76

77
### Execute in Package Context
78

79
Execute arbitrary commands with access to locally installed packages.
80

81
```bash { .api }
82
/**
83
 * Execute commands in package context
84
 * Runs commands with node_modules/.bin in PATH
85
 */
86
pnpm exec <command> [options]
87
```
88

89
**Options:**
90
- `--recursive`, `-r` - Execute in all workspace packages
91
- `--filter <pattern>` - Execute in filtered packages
92
- `--parallel` - Execute in parallel across workspaces
93

94
**Usage Examples:**
95

96
```bash
97
# Run TypeScript compiler
98
pnpm exec tsc
99

100
# Check installed package version
101
pnpm exec -- webpack --version
102

103
# Run in all workspaces
104
pnpm exec -r -- eslint .
105

106
# Run in filtered packages
107
pnpm exec --filter "frontend-*" -- jest
108
```
109

110
### Create Projects from Templates
111

112
Create new projects using create-* templates with initialization and setup.
113

114
```bash { .api }
115
/**
116
 * Create projects from templates
117
 * Uses create-* packages to scaffold new projects
118
 */
119
pnpm create <template> [options]
120
```
121

122
**Usage Examples:**
123

124
```bash
125
# Create React app
126
pnpm create react-app my-app
127

128
# Create Next.js app
129
pnpm create next-app my-next-app
130

131
# Create Vite project
132
pnpm create vite my-vite-app
133

134
# Create with TypeScript
135
pnpm create next-app --typescript my-ts-app
136
```
137

138
### Restart Services
139

140
Restart application by running stop and start scripts in sequence.
141

142
```bash { .api }
143
/**
144
 * Restart application services
145
 * Runs npm stop followed by npm start
146
 */
147
pnpm restart [options]
148
```
149

150
**Options:**
151
- `--recursive`, `-r` - Restart in all workspace packages
152
- `--filter <pattern>` - Restart in filtered packages
153

154
**Usage Examples:**
155

156
```bash
157
# Restart current package
158
pnpm restart
159

160
# Restart all services in workspace
161
pnpm restart -r
162

163
# Restart specific services
164
pnpm restart --filter "api-*"
165
```
166

167
### Install and Test
168

169
Install dependencies and immediately run tests - useful for CI environments.
170

171
```bash { .api }
172
/**
173
 * Install dependencies and run tests
174
 * Combines install and test steps for CI workflows
175
 */
176
pnpm install-test [options]
177
pnpm it [options]
178
```
179

180
**Usage Examples:**
181

182
```bash
183
# Install and test
184
pnpm install-test
185

186
# Install and test with options
187
pnpm it --frozen-lockfile
188
```
189

190
## Script Context and Environment
191

192
### Environment Variables
193

194
pnpm sets up the following environment variables when running scripts:
195

196
```bash { .api }
197
# Available in all scripts
198
npm_command          # Current command name (e.g., 'run', 'test')
199
npm_lifecycle_event  # Current script name (e.g., 'dev', 'build')
200
npm_package_name     # Package name from package.json
201
npm_package_version  # Package version from package.json
202
PNPM_SCRIPT_SRC_DIR  # Directory containing package.json
203
```
204

205
### PATH Setup
206

207
pnpm automatically adds the following to PATH during script execution:
208

209
```bash { .api }
210
# Directories added to PATH
211
./node_modules/.bin              # Local package binaries
212
<store>/node_modules/.bin        # Global store binaries
213
<workspace-root>/node_modules/.bin  # Workspace root binaries (if applicable)
214
```
215

216
### Lifecycle Scripts
217

218
pnpm respects npm lifecycle scripts and runs them automatically:
219

220
```bash { .api }
221
# Pre/post scripts run automatically
222
prestart    # Before 'start' script
223
start       # Main start script  
224
poststart   # After 'start' script
225

226
prebuild    # Before 'build' script
227
build       # Main build script
228
postbuild   # After 'build' script
229

230
pretest     # Before 'test' script
231
test        # Main test script
232
posttest    # After 'test' script
233
```
234

235
## Workspace Script Execution
236

237
### Parallel Execution
238

239
Run scripts across multiple workspace packages simultaneously:
240

241
```bash { .api }
242
# Run scripts in parallel
243
pnpm run -r --parallel build
244
pnpm run -r --parallel test
245

246
# Control concurrency
247
pnpm run -r --parallel --max-workers=4 build
248
```
249

250
### Sequential Execution
251

252
Run scripts in dependency order across workspace packages:
253

254
```bash { .api }
255
# Run in topological order
256
pnpm run -r build
257

258
# Run with dependency awareness
259
pnpm run -r --workspace-concurrency=1 build
260
```
261

262
### Filtering
263

264
Execute scripts only in specific workspace packages:
265

266
```bash { .api }
267
# Filter by package name pattern
268
pnpm run --filter "*api*" build
269
pnpm run --filter "@myorg/*" test
270

271
# Filter by changed files
272
pnpm run --filter "...[HEAD~1]" test
273

274
# Filter by dependencies
275
pnpm run --filter "...@myorg/core" build
276
```
277

278
## Error Handling
279

280
### Exit Codes
281

282
pnpm preserves exit codes from executed scripts:
283

284
```bash { .api }
285
# Script exits with code 1 on failure
286
pnpm run test  # exits with 1 if tests fail
287

288
# Continue on error in workspaces
289
pnpm run -r --no-bail test  # continues even if some tests fail
290
```
291

292
### Failure Handling
293

294
Control behavior when scripts fail in workspace scenarios:
295

296
```bash { .api }
297
# Stop on first failure (default)
298
pnpm run -r test
299

300
# Continue despite failures
301
pnpm run -r --no-bail test
302

303
# Report all results
304
pnpm run -r --reporter=append-only test
305
```