0
# Projen
1

2
Projen is a comprehensive software project configuration management system that provides a Cloud Development Kit (CDK) approach to defining and maintaining complex project configurations through code. It synthesizes project configuration files such as `package.json`, `tsconfig.json`, `.gitignore`, GitHub Workflows, eslint, jest, and other essential project files from well-typed JavaScript/TypeScript definitions. Unlike traditional templating or scaffolding tools, projen is not a one-off generator but maintains ongoing project configuration management through code, enforcing that synthesized files should never be manually edited.
3

4
## Package Information
5

6
- **Package Name**: projen
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install projen`
10
- **Peer Dependencies**: `constructs ^10.0.0`
11

12
## Core Imports
13

14
```typescript
15
import { Project, Component, Task, Dependencies } from "projen";
16
import { TypeScriptProject, NodeProject, PythonProject, JavaProject } from "projen";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { Project, Component, Task, Dependencies } = require("projen");
23
const { TypeScriptProject, NodeProject, PythonProject, JavaProject } = require("projen");
24
```
25

26
For submodules:
27

28
```typescript
29
import { typescript, javascript, python, java, github, awscdk } from "projen";
30
import { TypeScriptProject } from "projen/lib/typescript";
31
```
32

33
## Basic Usage
34

35
```typescript
36
import { TypeScriptProject } from "projen";
37

38
// Create a new TypeScript project
39
const project = new TypeScriptProject({
40
  name: "my-awesome-project",
41
  defaultReleaseBranch: "main",
42
  author: "Jane Developer",
43
  authorEmail: "jane@example.com",
44
  repository: "https://github.com/user/my-awesome-project.git",
45
  
46
  // TypeScript configuration
47
  srcdir: "src",
48
  testdir: "test",
49
  libdir: "lib",
50
  
51
  // Dependencies
52
  deps: ["axios", "lodash"],
53
  devDeps: ["@types/node", "@types/jest"],
54
  
55
  // Testing
56
  jest: true,
57
  eslint: true,
58
  prettier: true,
59
});
60

61
// Add custom tasks
62
project.addTask("custom-build", {
63
  description: "Custom build process",
64
  exec: "echo 'Running custom build'",
65
});
66

67
// Synthesize all project files
68
project.synth();
69
```
70

71
## Architecture
72

73
Projen is built around several key architectural concepts:
74

75
- **Project Hierarchy**: Base `Project` class extended by language-specific projects like `TypeScriptProject`, `PythonProject`, etc.
76
- **Component System**: Everything is a `Component` that can be added to projects - from file management to CI/CD workflows
77
- **Synthesis Process**: Projects synthesize configuration files during the build process, maintaining consistency across updates
78
- **Task System**: Unified task execution across different project types with dependency management
79
- **File Management**: Abstract file system with support for JSON, YAML, text files, and generated code
80
- **Construct Integration**: Built on AWS CDK's construct model for composability and extensibility
81

82
## Capabilities
83

84
### Core Project Management
85

86
Foundation classes and utilities for creating and managing software projects of any type.
87

88
```typescript { .api }
89
class Project extends Construct {
90
  constructor(options: ProjectOptions);
91
  readonly name: string;
92
  readonly outdir: string;
93
  readonly tasks: Tasks;
94
  readonly deps: Dependencies;
95
  addTask(name: string, props?: TaskOptions): Task;
96
  synth(): void;
97
  static of(construct: IConstruct): Project;
98
}
99

100
interface ProjectOptions {
101
  name: string;
102
  parent?: Project;
103
  outdir?: string;
104
  logging?: LoggerOptions;
105
  projenrcJson?: boolean;
106
  renovatebot?: boolean;
107
  commitGenerated?: boolean;
108
}
109
```
110

111
[Core Project Management](./core-project.md)
112

113
### TypeScript Projects
114

115
Complete TypeScript project setup with compilation, testing, linting, and documentation generation.
116

117
```typescript { .api }
118
class TypeScriptProject extends NodeProject {
119
  constructor(options: TypeScriptProjectOptions);
120
  readonly srcdir: string;
121
  readonly libdir: string;
122
  readonly testdir: string;
123
  readonly tsconfig?: TypescriptConfig;
124
  readonly tsconfigDev: TypescriptConfig;
125
  readonly watchTask: Task;
126
}
127
```
128

129
[TypeScript Projects](./typescript-projects.md)
130

131
### Node.js Projects
132

133
Node.js projects with package management, testing frameworks, and JavaScript tooling.
134

135
```typescript { .api }
136
class NodeProject extends GitHubProject {
137
  constructor(options: NodeProjectOptions);
138
  readonly package: NodePackage;
139
  readonly jest?: Jest;
140
  readonly eslint?: Eslint;
141
  readonly prettier?: Prettier;
142
  readonly bundler?: Bundler;
143
}
144
```
145

146
[Node.js Projects](./nodejs-projects.md)
147

148
### Python Projects
149

150
Python projects with packaging, virtual environments, and testing frameworks.
151

152
```typescript { .api }
153
class PythonProject extends GitHubProject {
154
  constructor(options: PythonProjectOptions);
155
  readonly moduleName: string;
156
  readonly pip?: Pip;
157
  readonly poetry?: Poetry;
158
  readonly venv?: Venv;
159
  readonly pytest?: Pytest;
160
}
161
```
162

163
[Python Projects](./python-projects.md)
164

165
### Java Projects
166

167
Java projects with Maven build system and dependency management.
168

169
```typescript { .api }
170
class JavaProject extends GitHubProject {
171
  constructor(options: JavaProjectOptions);
172
  readonly pom: Pom;
173
  readonly junit?: Junit;
174
  readonly packaging: MavenPackaging;
175
  readonly compile: MavenCompile;
176
}
177
```
178

179
[Java Projects](./java-projects.md)
180

181
### Web Projects
182

183
React and Next.js projects with modern web development tooling.
184

185
```typescript { .api }
186
class ReactProject extends NodeProject {
187
  constructor(options: ReactProjectOptions);
188
}
189

190
class NextJsProject extends NodeProject {
191
  constructor(options: NextJsProjectOptions);
192
}
193
```
194

195
[Web Projects](./web-projects.md)
196

197
### AWS CDK Projects
198

199
AWS CDK applications and construct libraries for cloud infrastructure.
200

201
```typescript { .api }
202
class AwsCdkTypeScriptApp extends TypeScriptProject {
203
  constructor(options: AwsCdkTypeScriptAppOptions);
204
}
205

206
class AwsCdkConstructLibrary extends ConstructLibrary {
207
  constructor(options: AwsCdkConstructLibraryOptions);
208
}
209
```
210

211
[AWS CDK Projects](./awscdk-projects.md)
212

213
### Task Management
214

215
Unified task system for build processes, testing, and custom workflows.
216

217
```typescript { .api }
218
class Task {
219
  constructor(name: string, props?: TaskOptions);
220
  readonly name: string;
221
  exec(command: string, options?: TaskStepOptions): void;
222
  spawn(subtask: string, options?: TaskStepOptions): void;
223
  lock(): void;
224
}
225

226
interface TaskOptions {
227
  description?: string;
228
  exec?: string;
229
  steps?: TaskStep[];
230
  env?: Record<string, string>;
231
  cwd?: string;
232
  condition?: string;
233
}
234
```
235

236
[Task Management](./task-management.md)
237

238
### Dependency Management
239

240
Cross-platform dependency management for different package managers.
241

242
```typescript { .api }
243
class Dependencies extends Component {
244
  constructor(project: Project);
245
  addDependency(spec: string, type: DependencyType, metadata?: object): Dependency;
246
  removeDependency(name: string, type?: DependencyType): void;
247
  getDependency(name: string, type?: DependencyType): Dependency;
248
}
249

250
enum DependencyType {
251
  RUNTIME = "runtime",
252
  PEER = "peer",
253
  BUNDLED = "bundled",
254
  BUILD = "build",
255
  TEST = "test",
256
  DEVENV = "devenv",
257
  OVERRIDE = "override",
258
  OPTIONAL = "optional"
259
}
260
```
261

262
[Dependency Management](./dependency-management.md)
263

264
### File Management
265

266
Abstract file system for managing configuration files, source code, and generated content.
267

268
```typescript { .api }
269
abstract class FileBase extends Component {
270
  constructor(scope: IConstruct, filePath: string, options?: FileBaseOptions);
271
  readonly path: string;
272
  readonly absolutePath: string;
273
  readonly readonly: boolean;
274
  readonly executable: boolean;
275
}
276

277
class JsonFile extends ObjectFile {
278
  constructor(scope: IConstruct, filePath: string, options?: JsonFileOptions);
279
}
280

281
class YamlFile extends ObjectFile {
282
  constructor(scope: IConstruct, filePath: string, options?: YamlFileOptions);
283
}
284
```
285

286
[File Management](./file-management.md)
287

288
### GitHub Integration
289

290
GitHub Actions workflows, issue templates, and repository management.
291

292
```typescript { .api }
293
class GitHub extends Component {
294
  constructor(project: GitHubProject, options?: GitHubOptions);
295
}
296

297
class GitHubProject extends Project {
298
  constructor(options: GitHubProjectOptions);
299
  readonly github?: GitHub;
300
}
301
```
302

303
[GitHub Integration](./github-integration.md)
304

305
## Types
306

307
### Core Types
308

309
```typescript { .api }
310
interface Component {
311
  readonly node: Node;
312
  readonly project: Project;
313
  toString(): string;
314
}
315

316
interface Dependency {
317
  name: string;
318
  version?: string;
319
  type: DependencyType;
320
  metadata?: object;
321
}
322

323
interface TaskStep {
324
  exec?: string;
325
  spawn?: string;
326
  builtin?: string;
327
  env?: Record<string, string>;
328
  cwd?: string;
329
  condition?: string;
330
}
331

332
interface LoggerOptions {
333
  level?: LogLevel;
334
  usePrefix?: boolean;
335
}
336

337
enum LogLevel {
338
  OFF = 0,
339
  ERROR = 1,
340
  WARN = 2,
341
  INFO = 3,
342
  DEBUG = 4,
343
  VERBOSE = 5
344
}
345
```