0
# Task Management
1

2
Unified task system for build processes, testing, and custom workflows. Projen's task system provides a consistent interface for defining and executing project tasks across different project types.
3

4
## Capabilities
5

6
### Task Class
7

8
Individual task that can execute shell commands and spawn subtasks.
9

10
```typescript { .api }
11
/**
12
 * Represents a project task with shell commands and subtask execution
13
 * Tasks are the building blocks of project automation
14
 */
15
class Task {
16
  constructor(name: string, props?: TaskOptions);
17
  
18
  /** Task identifier */
19
  readonly name: string;
20
  /** Working directory for task execution */
21
  readonly cwd?: string;
22
  /** Task description */
23
  readonly description?: string;
24
  /** Environment variables for task */
25
  readonly env?: Record<string, string>;
26
  /** Task steps to execute */
27
  readonly steps: TaskStep[];
28
  
29
  /** Add a shell command to execute */
30
  exec(command: string, options?: TaskStepOptions): void;
31
  /** Add a subtask to spawn */
32
  spawn(subtask: string, options?: TaskStepOptions): void;
33
  /** Add a built-in task step */
34
  builtin(name: string): void;
35
  /** Prevent further modifications to the task */
36
  lock(): void;
37
}
38

39
interface TaskOptions {
40
  /** Human-readable description of what the task does */
41
  description?: string;
42
  /** Initial shell command to execute */
43
  exec?: string;
44
  /** List of task steps to perform */
45
  steps?: TaskStep[];
46
  /** Environment variables for the task */
47
  env?: Record<string, string>;
48
  /** Working directory (relative to project root) */
49
  cwd?: string;
50
  /** Condition for task execution */
51
  condition?: string;
52
}
53

54
interface TaskStep {
55
  /** Shell command to execute */
56
  exec?: string;
57
  /** Subtask to spawn */
58
  spawn?: string;
59
  /** Built-in task to execute */
60
  builtin?: string;
61
  /** Environment variables for this step */
62
  env?: Record<string, string>;
63
  /** Working directory for this step */
64
  cwd?: string;
65
  /** Condition for step execution */
66
  condition?: string;
67
}
68

69
interface TaskStepOptions {
70
  /** Environment variables */
71
  env?: Record<string, string>;
72
  /** Working directory */
73
  cwd?: string;
74
  /** Execution condition */
75
  condition?: string;
76
}
77
```
78

79
**Basic Task Usage:**
80

81
```typescript
82
import { Project } from "projen";
83

84
const project = new Project({ name: "task-example" });
85

86
// Simple task with single command
87
const buildTask = project.addTask("build", {
88
  description: "Build the project",
89
  exec: "tsc",
90
});
91

92
// Complex task with multiple steps
93
const testTask = project.addTask("test", {
94
  description: "Run tests with coverage",
95
});
96

97
testTask.exec("npm run lint");
98
testTask.exec("jest --coverage", {
99
  env: { NODE_ENV: "test" },
100
});
101
testTask.spawn("build"); // Run build task first
102

103
// Task with conditions
104
const deployTask = project.addTask("deploy", {
105
  description: "Deploy to production",
106
  condition: "$CI && $BRANCH == 'main'",
107
});
108

109
deployTask.exec("npm run build");
110
deployTask.exec("aws s3 sync ./dist s3://my-bucket");
111
```
112

113
### Tasks Registry
114

115
Central registry for managing all project tasks.
116

117
```typescript { .api }
118
/**
119
 * Task registry for a project - manages all tasks
120
 * Provides methods for adding, removing, and finding tasks
121
 */
122
class Tasks extends Component {
123
  constructor(project: Project);
124
  
125
  /** All tasks in the project */
126
  readonly all: Task[];
127
  
128
  /** Add a new task to the project */
129
  addTask(name: string, props?: TaskOptions): Task;
130
  /** Remove a task from the project */
131
  removeTask(name: string): Task | undefined;
132
  /** Find a task by name */
133
  tryFindTask(name: string): Task | undefined;
134
  /** Check if a task exists */
135
  hasTask(name: string): boolean;
136
}
137
```
138

139
**Tasks Registry Example:**
140

141
```typescript
142
import { Project } from "projen";
143

144
const project = new Project({ name: "registry-example" });
145

146
// Add multiple related tasks
147
project.tasks.addTask("clean", {
148
  description: "Clean build artifacts",
149
  exec: "rm -rf dist/",
150
});
151

152
project.tasks.addTask("compile", {
153
  description: "Compile TypeScript",
154
  exec: "tsc",
155
});
156

157
project.tasks.addTask("bundle", {
158
  description: "Bundle application",
159
  exec: "webpack --mode production",
160
});
161

162
// Create composite task
163
const buildTask = project.tasks.addTask("build", {
164
  description: "Full build process",
165
});
166

167
buildTask.spawn("clean");
168
buildTask.spawn("compile");
169
buildTask.spawn("bundle");
170

171
// Check if task exists
172
if (project.tasks.hasTask("test")) {
173
  const testTask = project.tasks.tryFindTask("test");
174
  testTask?.exec("echo 'Running tests'");
175
}
176
```
177

178
### Built-in Tasks
179

180
Common built-in tasks available across project types.
181

182
```typescript { .api }
183
/**
184
 * Built-in task steps that are commonly used
185
 * These provide cross-platform functionality
186
 */
187
interface BuiltinTasks {
188
  /** Remove files and directories */
189
  "rm": { paths: string[] };
190
  /** Copy files */
191
  "cp": { source: string; target: string };
192
  /** Create directories */
193
  "mkdir": { path: string };
194
  /** Echo text to console */
195
  "echo": { message: string };
196
}
197
```
198

199
**Built-in Tasks Example:**
200

201
```typescript
202
import { Project } from "projen";
203

204
const project = new Project({ name: "builtin-example" });
205

206
const setupTask = project.addTask("setup", {
207
  description: "Setup project directories",
208
});
209

210
// Use built-in tasks for cross-platform compatibility
211
setupTask.builtin("mkdir -p dist");
212
setupTask.builtin("mkdir -p temp");
213
setupTask.builtin("echo 'Setup complete'");
214

215
const cleanTask = project.addTask("clean", {
216
  description: "Clean generated files",
217
});
218

219
cleanTask.builtin("rm -rf dist");
220
cleanTask.builtin("rm -rf temp");
221
```
222

223
### Task Runtime
224

225
Task execution runtime and environment management.
226

227
```typescript { .api }
228
/**
229
 * Task execution runtime - handles task execution
230
 * Manages environment, logging, and execution context
231
 */
232
class TaskRuntime {
233
  constructor(workdir: string, options?: TaskRuntimeOptions);
234
  
235
  /** Execute a task by name */
236
  runTask(name: string, args?: string[]): Promise<void>;
237
  /** List all available tasks */
238
  listTasks(): Task[];
239
  /** Get task by name */
240
  tryFindTask(name: string): Task | undefined;
241
}
242

243
interface TaskRuntimeOptions {
244
  /** Environment variables */
245
  env?: Record<string, string>;
246
  /** Logging options */
247
  logging?: LoggerOptions;
248
  /** Parallel task execution */
249
  parallel?: boolean;
250
}
251
```
252

253
### Advanced Task Features
254

255
Advanced task configuration and execution patterns.
256

257
```typescript { .api }
258
/**
259
 * Task model for complex task definitions
260
 * Supports conditions, dependencies, and metadata
261
 */
262
class TaskModel {
263
  constructor(name: string, definition: TaskDefinition);
264
  
265
  readonly name: string;
266
  readonly description?: string;
267
  readonly condition?: string;
268
  readonly dependencies?: string[];
269
  readonly metadata?: Record<string, any>;
270
}
271

272
interface TaskDefinition {
273
  description?: string;
274
  steps: TaskStep[];
275
  condition?: string;
276
  dependencies?: string[];
277
  metadata?: Record<string, any>;
278
}
279
```
280

281
**Advanced Task Example:**
282

283
```typescript
284
import { TypeScriptProject } from "projen";
285

286
const project = new TypeScriptProject({
287
  name: "advanced-tasks",
288
});
289

290
// Task with dependencies and conditions
291
const deployTask = project.addTask("deploy", {
292
  description: "Deploy application to production",
293
  condition: "$CI == 'true' && $BRANCH == 'main'",
294
});
295

296
// Ensure build happens first
297
deployTask.spawn("build");
298

299
// Deploy steps with different conditions
300
deployTask.exec("echo 'Deploying to staging'", {
301
  condition: "$ENVIRONMENT == 'staging'",
302
});
303

304
deployTask.exec("echo 'Deploying to production'", {
305
  condition: "$ENVIRONMENT == 'production'",
306
});
307

308
// Post-deploy notifications
309
deployTask.exec("curl -X POST $SLACK_WEBHOOK -d 'Deployment complete'", {
310
  condition: "$SLACK_WEBHOOK",
311
});
312

313
// Task with custom environment
314
const testTask = project.addTask("test:integration", {
315
  description: "Run integration tests",
316
  env: {
317
    NODE_ENV: "test",
318
    DATABASE_URL: "postgres://localhost:5432/test_db",
319
  },
320
});
321

322
testTask.exec("jest --config jest.integration.config.js");
323
```
324

325
### Task Workflows
326

327
Converting tasks to CI/CD workflows.
328

329
```typescript { .api }
330
/**
331
 * Convert projen tasks to GitHub Actions workflows
332
 * Enables running tasks in CI/CD environments
333
 */
334
class TaskWorkflow extends Component {
335
  constructor(github: GitHub, options: TaskWorkflowOptions);
336
}
337

338
interface TaskWorkflowOptions {
339
  /** Task name to convert to workflow */
340
  task: string;
341
  /** Workflow trigger events */
342
  triggers?: WorkflowTriggers;
343
  /** Workflow name */
344
  name?: string;
345
  /** Job configuration */
346
  jobSettings?: JobSettings;
347
}
348
```
349

350
## Types
351

352
### Task-Related Types
353

354
```typescript { .api }
355
interface WorkflowTriggers {
356
  /** Push triggers */
357
  push?: {
358
    branches?: string[];
359
    paths?: string[];
360
  };
361
  /** Pull request triggers */
362
  pullRequest?: {
363
    branches?: string[];
364
    paths?: string[];
365
  };
366
  /** Schedule triggers */
367
  schedule?: Array<{
368
    cron: string;
369
  }>;
370
  /** Manual workflow dispatch */
371
  workflowDispatch?: boolean;
372
}
373

374
interface JobSettings {
375
  /** Job runner (ubuntu-latest, windows-latest, etc.) */
376
  runsOn?: string;
377
  /** Job timeout in minutes */
378
  timeoutMinutes?: number;
379
  /** Environment variables */
380
  env?: Record<string, string>;
381
  /** Job permissions */
382
  permissions?: Record<string, string>;
383
}
384
```