0
# Core Project Management
1

2
Foundation classes and utilities for creating and managing software projects of any type. These are the base building blocks that all other project types extend.
3

4
## Capabilities
5

6
### Project Class
7

8
The base project class that all projen projects extend. Manages file synthesis, task execution, and component coordination.
9

10
```typescript { .api }
11
/**
12
 * Base project class - foundation for all projen projects
13
 * Extends the AWS CDK Construct class for composability
14
 */
15
class Project extends Construct {
16
  constructor(options: ProjectOptions);
17
  
18
  /** Project name */
19
  readonly name: string;
20
  /** Absolute output directory path */
21
  readonly outdir: string;
22
  /** Parent project for subprojects */
23
  readonly parent?: Project;
24
  /** Task management system */
25
  readonly tasks: Tasks;
26
  /** Dependency management system */
27
  readonly deps: Dependencies;
28
  /** Logging utilities */
29
  readonly logger: Logger;
30
  /** .gitignore file management */
31
  readonly gitignore: IgnoreFile;
32
  /** .gitattributes file management */
33
  readonly gitattributes: GitAttributesFile;
34
  /** Build process coordination */
35
  readonly projectBuild: ProjectBuild;
36
  
37
  /** Add a new task to the project */
38
  addTask(name: string, props?: TaskOptions): Task;
39
  /** Remove a task from the project */
40
  removeTask(name: string): Task | undefined;
41
  /** Synthesize all project files to disk */
42
  synth(): void;
43
  /** Find a file by relative path */
44
  tryFindFile(filePath: string): FileBase | undefined;
45
  /** Find a JSON file by relative path */
46
  tryFindJsonFile(filePath: string): JsonFile | undefined;
47
  /** Find an object file by relative path */
48
  tryFindObjectFile(filePath: string): ObjectFile | undefined;
49
  /** Remove a file from the project */
50
  tryRemoveFile(filePath: string): FileBase | undefined;
51
  /** Add a pattern to .gitignore */
52
  addGitIgnore(pattern: string): void;
53
  /** Add a tip message to be displayed after synthesis */
54
  addTip(message: string): void;
55
  /** Add glob patterns to exclude from cleanup */
56
  addExcludeFromCleanup(...globs: string[]): void;
57
  /** Add pattern to package ignore list */
58
  addPackageIgnore(pattern: string): void;
59
  /** Run a task command in the project directory */
60
  runTaskCommand(task: Task): void;
61
  /** Annotate a file pattern as generated */
62
  annotateGenerated(glob: string): void;
63
  
64
  /** Get the root project */
65
  readonly root: Project;
66
  /** Get all components in the project */
67
  readonly components: Component[];
68
  /** Get all subprojects */
69
  readonly subprojects: Project[];
70
  /** Get all files in the project */
71
  readonly files: FileBase[];
72
  /** Check if project has been ejected */
73
  readonly ejected: boolean;
74
  /** Default task (usually runs when `projen` is called without arguments) */
75
  readonly defaultTask?: Task;
76
  /** Build task */
77
  readonly buildTask: Task;
78
  /** Compile task */
79
  readonly compileTask: Task;
80
  /** Test task */
81
  readonly testTask: Task;
82
  /** Pre-compile task */
83
  readonly preCompileTask: Task;
84
  /** Post-compile task */
85
  readonly postCompileTask: Task;
86
  /** Package task */
87
  readonly packageTask: Task;
88
  /** Shell command to run projen CLI */
89
  readonly projenCommand: string;
90
  /** Whether generated files should be committed */
91
  readonly commitGenerated: boolean;
92
  /** Project initialization metadata (for programmatic creation) */
93
  readonly initProject?: InitProject;
94
  
95
  /** Type guard to check if object is a Project */
96
  static isProject(x: any): x is Project;
97
  /** Get the project instance from any construct */
98
  static of(construct: IConstruct): Project;
99
}
100

101
interface ProjectOptions {
102
  /** Project name - used for package.json name, directory names, etc. */
103
  name: string;
104
  /** Parent project for creating subprojects */
105
  parent?: Project;
106
  /** Output directory (default: process.cwd()) */
107
  outdir?: string;
108
  /** Logging configuration */
109
  logging?: LoggerOptions;
110
  /** Generate .projenrc.json for JSON-based configuration */
111
  projenrcJson?: boolean;
112
  /** Options for .projenrc.json */
113
  projenrcJsonOptions?: ProjenrcJsonOptions;
114
  /** Shell command to run projen CLI (default: "npx projen") */
115
  projenCommand?: string;
116
  /** Enable Renovatebot for dependency updates */
117
  renovatebot?: boolean;
118
  /** Options for renovatebot */
119
  renovatebotOptions?: RenovatebotOptions;
120
  /** Commit generated files to git (default: true) */
121
  commitGenerated?: boolean;
122
  /** Git configuration options */
123
  gitOptions?: GitOptions;
124
  /** .gitignore file configuration options */
125
  gitIgnoreOptions?: IgnoreFileOptions;
126
}
127

128
interface GitOptions {
129
  /** File patterns to mark as stored in Git LFS */
130
  lfsPatterns?: string[];
131
  /** The default end of line character for text files */
132
  endOfLine?: EndOfLine;
133
}
134

135
interface IgnoreFileOptions {
136
  /** File patterns to ignore */
137
  ignorePatterns?: string[];
138
}
139

140
interface LoggerOptions {
141
  /** Logging level */
142
  level?: LogLevel;
143
  /** Use prefix in log messages */
144
  usePrefix?: boolean;
145
}
146

147
enum LogLevel {
148
  OFF = 0,
149
  ERROR = 1,
150
  WARN = 2,
151
  INFO = 3,
152
  DEBUG = 4,
153
  VERBOSE = 5
154
}
155

156
enum EndOfLine {
157
  /** Maintain existing (mixed values within one file are normalised by looking at what's used after the first line) */
158
  AUTO = "auto",
159
  /** Carriage Return + Line Feed characters (\r\n), common on Windows */
160
  CRLF = "crlf",
161
  /** Line Feed only (\n), common on Linux and macOS as well as inside git repos */
162
  LF = "lf",
163
  /** Disable and do not configure the end of line character */
164
  NONE = "none"
165
}
166
```
167

168
**Usage Example:**
169

170
```typescript
171
import { Project } from "projen";
172

173
const project = new Project({
174
  name: "my-base-project",
175
  outdir: "./output",
176
  logging: { level: LogLevel.INFO },
177
  renovatebot: true,
178
});
179

180
// Add custom task
181
const buildTask = project.addTask("build", {
182
  description: "Build the project",
183
  exec: "echo 'Building project'",
184
});
185

186
// Synthesize files
187
project.synth();
188
```
189

190
### Component Class
191

192
Base class for all project components. Components are composable units that add functionality to projects.
193

194
```typescript { .api }
195
/**
196
 * Base class for all project components
197
 * Provides synthesis lifecycle hooks
198
 */
199
class Component extends Construct {
200
  constructor(scope: IConstruct, id?: string);
201
  
202
  /** Reference to the parent project */
203
  readonly project: Project;
204
  
205
  /** Pre-synthesis hook - called before synthesis */
206
  preSynthesize(): void;
207
  /** Main synthesis hook - generate files and configuration */
208
  synthesize(): void;
209
  /** Post-synthesis hook - called after synthesis */
210
  postSynthesize(): void;
211
  
212
  /** Type guard to check if object is a Component */
213
  static isComponent(x: any): x is Component;
214
}
215
```
216

217
**Usage Example:**
218

219
```typescript
220
import { Component, Project } from "projen";
221

222
class CustomComponent extends Component {
223
  constructor(project: Project) {
224
    super(project, "custom-component");
225
  }
226
  
227
  synthesize() {
228
    // Add custom synthesis logic
229
    new JsonFile(this.project, "custom-config.json", {
230
      obj: { custom: true },
231
    });
232
  }
233
}
234

235
const project = new Project({ name: "test" });
236
new CustomComponent(project);
237
project.synth();
238
```
239

240
### Projects Utility Class
241

242
Static utility class for programmatic project creation and management.
243

244
```typescript { .api }
245
/**
246
 * Utility class for programmatic project creation
247
 * Provides factory methods for creating projects
248
 */
249
class Projects {
250
  /** Create a project programmatically with specified options */
251
  static createProject(options: CreateProjectOptions): void;
252
}
253

254
interface CreateProjectOptions {
255
  /** Directory to create the project in */
256
  dir: string;
257
  /** Project type identifier */
258
  projectType: string;
259
  /** Project configuration options */
260
  projectOptions: any;
261
  /** Skip synthesis after creation */
262
  skipSynth?: boolean;
263
}
264
```
265

266
**Usage Example:**
267

268
```typescript
269
import { Projects } from "projen";
270

271
// Create a TypeScript project programmatically
272
Projects.createProject({
273
  dir: "./my-new-project",
274
  projectType: "typescript",
275
  projectOptions: {
276
    name: "my-typescript-project",
277
    defaultReleaseBranch: "main",
278
  },
279
});
280
```
281

282
### Project Build System
283

284
Coordinates the build process across all project components.
285

286
```typescript { .api }
287
/**
288
 * Manages the project build process and component coordination
289
 */
290
class ProjectBuild extends Component {
291
  constructor(project: Project);
292
  
293
  /** Pre-build phase tasks */
294
  readonly preBuildTask: Task;
295
  /** Main build phase tasks */
296
  readonly buildTask: Task;
297
  /** Post-build phase tasks */
298
  readonly postBuildTask: Task;
299
}
300
```
301

302
### Logger System
303

304
Structured logging system with configurable levels and formatting.
305

306
```typescript { .api }
307
/**
308
 * Structured logging with different levels and formatting
309
 */
310
class Logger {
311
  constructor(options?: LoggerOptions);
312
  
313
  /** Log verbose message (level 5) */
314
  verbose(message: string): void;
315
  /** Log debug message (level 4) */
316
  debug(message: string): void;
317
  /** Log info message (level 3) */
318
  info(message: string): void;
319
  /** Log warning message (level 2) */
320
  warn(message: string): void;
321
  /** Log error message (level 1) */
322
  error(message: string): void;
323
}
324
```
325

326
**Usage Example:**
327

328
```typescript
329
import { Logger, LogLevel } from "projen";
330

331
const logger = new Logger({
332
  level: LogLevel.DEBUG,
333
  usePrefix: true,
334
});
335

336
logger.info("Starting project synthesis");
337
logger.debug("Component configuration loaded");
338
logger.warn("Deprecated option used");
339
```