0
# Dependency Management
1

2
Cross-platform dependency management for different package managers. Projen provides a unified interface for managing dependencies across npm, pip, Maven, and other package ecosystems.
3

4
## Capabilities
5

6
### Dependencies Class
7

8
Central dependency management system that works across different package managers.
9

10
```typescript { .api }
11
/**
12
 * Manages project dependencies across different package managers
13
 * Provides unified interface for npm, pip, Maven, etc.
14
 */
15
class Dependencies extends Component {
16
  constructor(project: Project);
17
  
18
  /** All dependencies in the project */
19
  readonly all: Dependency[];
20
  
21
  /** Add a dependency to the project */
22
  addDependency(spec: string, type: DependencyType, metadata?: object): Dependency;
23
  /** Remove a dependency from the project */
24
  removeDependency(name: string, type?: DependencyType): void;
25
  /** Get a dependency by name and type */
26
  getDependency(name: string, type?: DependencyType): Dependency;
27
  /** Try to get a dependency (returns undefined if not found) */
28
  tryGetDependency(name: string, type?: DependencyType): Dependency | undefined;
29
  /** Check if a dependency version requirement is satisfied */
30
  isDependencySatisfied(name: string, type: DependencyType, expectedRange: string): boolean;
31
  
32
  /** Parse a dependency specification string */
33
  static parseDependency(spec: string): DependencyCoordinates;
34
}
35

36
interface Dependency {
37
  /** Package name */
38
  name: string;
39
  /** Version requirement (semver range, exact version, etc.) */
40
  version?: string;
41
  /** Dependency type classification */
42
  type: DependencyType;
43
  /** Additional metadata (registry, source, etc.) */
44
  metadata?: object;
45
}
46

47
interface DependencyCoordinates {
48
  /** Package name */
49
  name: string;
50
  /** Version specification */
51
  version?: string;
52
  /** Package source/registry */
53
  source?: string;
54
}
55

56
enum DependencyType {
57
  /** Runtime dependencies - required for production */
58
  RUNTIME = "runtime",
59
  /** Peer dependencies - provided by consuming application */
60
  PEER = "peer",
61
  /** Bundled dependencies - included in package distribution */
62
  BUNDLED = "bundled",
63
  /** Build dependencies - required for building */
64
  BUILD = "build",
65
  /** Test dependencies - required for testing only */
66
  TEST = "test",
67
  /** Development environment dependencies */
68
  DEVENV = "devenv",
69
  /** Override dependencies - override transitive dependency versions */
70
  OVERRIDE = "override",
71
  /** Optional dependencies - not required but enhance functionality */
72
  OPTIONAL = "optional"
73
}
74
```
75

76
**Basic Dependency Management:**
77

78
```typescript
79
import { Project, DependencyType } from "projen";
80

81
const project = new Project({ name: "dependency-example" });
82

83
// Add runtime dependencies
84
project.deps.addDependency("axios@^1.0.0", DependencyType.RUNTIME);
85
project.deps.addDependency("lodash", DependencyType.RUNTIME, {
86
  source: "npm",
87
});
88

89
// Add development dependencies
90
project.deps.addDependency("@types/node", DependencyType.BUILD);
91
project.deps.addDependency("jest", DependencyType.TEST);
92

93
// Add peer dependencies
94
project.deps.addDependency("react@>=16.0.0", DependencyType.PEER);
95

96
// Check if dependency exists
97
const axios = project.deps.tryGetDependency("axios", DependencyType.RUNTIME);
98
if (axios) {
99
  console.log(`Axios version: ${axios.version}`);
100
}
101

102
// Remove a dependency
103
project.deps.removeDependency("lodash", DependencyType.RUNTIME);
104
```
105

106
### Node.js Package Management
107

108
Specialized dependency management for Node.js projects using npm/yarn.
109

110
```typescript { .api }
111
/**
112
 * Node.js package.json management
113
 * Handles npm/yarn dependencies and package configuration
114
 */
115
class NodePackage extends Component {
116
  constructor(project: NodeProject, options?: NodePackageOptions);
117
  
118
  /** Package name */
119
  readonly packageName: string;
120
  /** Package version */
121
  readonly version: string;
122
  /** Runtime dependencies */
123
  readonly deps: Record<string, string>;
124
  /** Development dependencies */
125
  readonly devDeps: Record<string, string>;
126
  /** Peer dependencies */
127
  readonly peerDeps: Record<string, string>;
128
  /** Optional dependencies */
129
  readonly optionalDeps: Record<string, string>;
130
  /** Bundled dependencies */
131
  readonly bundledDeps: string[];
132
  
133
  /** Add runtime dependency */
134
  addDep(spec: string): void;
135
  /** Add development dependency */
136
  addDevDep(spec: string): void;
137
  /** Add peer dependency */
138
  addPeerDep(spec: string): void;
139
  /** Add optional dependency */
140
  addOptionalDep(spec: string): void;
141
  /** Add bundled dependency */
142
  addBundledDep(spec: string): void;
143
  
144
  /** Remove any type of dependency */
145
  removeDep(name: string): void;
146
  /** Check if dependency exists */
147
  hasDep(name: string): boolean;
148
  
149
  /** Add npm script */
150
  addScript(name: string, command: string): void;
151
  /** Remove npm script */
152
  removeScript(name: string): void;
153
  
154
  /** Add package.json field */
155
  addField(name: string, value: any): void;
156
}
157

158
interface NodePackageOptions {
159
  /** Package name override */
160
  packageName?: string;
161
  /** Package version */
162
  version?: string;
163
  /** Package description */
164
  description?: string;
165
  /** Package keywords */
166
  keywords?: string[];
167
  /** Package license */
168
  license?: string;
169
  /** Author information */
170
  author?: string | AuthorOptions;
171
  /** Repository information */
172
  repository?: string | RepositoryOptions;
173
  /** Homepage URL */
174
  homepage?: string;
175
  /** Bug tracker URL */
176
  bugs?: string | BugsOptions;
177
}
178
```
179

180
**Node.js Package Example:**
181

182
```typescript
183
import { NodeProject } from "projen";
184

185
const project = new NodeProject({
186
  name: "my-node-package",
187
  version: "1.0.0",
188
  description: "Example Node.js package",
189
  
190
  // Dependencies
191
  deps: [
192
    "express@^4.18.0",
193
    "cors@^2.8.5",
194
  ],
195
  devDeps: [
196
    "@types/express",
197
    "@types/cors",
198
    "typescript",
199
    "jest",
200
  ],
201
  peerDeps: [
202
    "react@>=16.0.0",
203
  ],
204
});
205

206
// Add custom npm scripts
207
project.package.addScript("start", "node dist/index.js");
208
project.package.addScript("dev", "ts-node src/index.ts");
209

210
// Add custom package.json fields
211
project.package.addField("engines", {
212
  node: ">=16.0.0",
213
  npm: ">=8.0.0",
214
});
215

216
// Dynamic dependency management
217
project.package.addDep("moment@^2.29.0");
218
project.package.addDevDep("@types/moment");
219
```
220

221
### Python Dependency Management
222

223
Python-specific dependency management with pip, poetry, and setuptools.
224

225
```typescript { .api }
226
/**
227
 * Python pip dependency management
228
 * Manages requirements.txt and setup.py dependencies
229
 */
230
class Pip extends Component {
231
  constructor(project: PythonProject, options?: PipOptions);
232
  
233
  /** Install a package */
234
  addDependency(spec: string): void;
235
  /** Install a development dependency */
236
  addDevDependency(spec: string): void;
237
  /** Remove a dependency */
238
  removeDependency(name: string): void;
239
}
240

241
/**
242
 * Poetry dependency management for Python
243
 * Manages pyproject.toml and poetry.lock
244
 */
245
class Poetry extends Component {
246
  constructor(project: PythonProject, options?: PoetryOptions);
247
  
248
  /** Add runtime dependency */
249
  addDependency(name: string, requirement?: string): void;
250
  /** Add development dependency */
251
  addDevDependency(name: string, requirement?: string): void;
252
  /** Add dependency group */
253
  addGroup(name: string, dependencies: Record<string, string>): void;
254
}
255

256
interface PipOptions {
257
  /** Install from requirements.txt */
258
  installRequirements?: boolean;
259
  /** Requirements file name */
260
  requirementsFile?: string;
261
}
262

263
interface PoetryOptions {
264
  /** Poetry version */
265
  version?: string;
266
  /** Python version requirement */
267
  pythonVersion?: string;
268
  /** Poetry configuration */
269
  config?: Record<string, any>;
270
}
271
```
272

273
**Python Dependencies Example:**
274

275
```typescript
276
import { PythonProject } from "projen";
277

278
const project = new PythonProject({
279
  name: "my-python-package",
280
  moduleName: "my_package",
281
  
282
  // Use Poetry for dependency management
283
  poetry: true,
284
  
285
  // Dependencies
286
  deps: [
287
    "requests>=2.28.0",
288
    "click>=8.0.0",
289
  ],
290
  devDeps: [
291
    "pytest>=7.0.0",
292
    "black>=22.0.0",
293
    "mypy>=1.0.0",
294
  ],
295
});
296

297
// Add additional dependencies programmatically
298
if (project.poetry) {
299
  project.poetry.addDependency("pydantic", "^1.10.0");
300
  project.poetry.addDevDependency("pytest-cov", "^4.0.0");
301
  
302
  // Add dependency groups
303
  project.poetry.addGroup("docs", {
304
    "sphinx": "^5.0.0",
305
    "sphinx-rtd-theme": "^1.0.0",
306
  });
307
}
308
```
309

310
### Java Dependency Management
311

312
Maven-based dependency management for Java projects.
313

314
```typescript { .api }
315
/**
316
 * Maven POM file management for Java projects
317
 * Handles dependencies, plugins, and build configuration
318
 */
319
class Pom extends Component {
320
  constructor(project: JavaProject, options?: PomOptions);
321
  
322
  /** Add runtime dependency */
323
  addDependency(groupId: string, artifactId: string, version?: string, options?: MavenDependencyOptions): void;
324
  /** Add test dependency */
325
  addTestDependency(groupId: string, artifactId: string, version?: string): void;
326
  /** Add plugin */
327
  addPlugin(groupId: string, artifactId: string, version?: string, options?: MavenPluginOptions): void;
328
  /** Add repository */
329
  addRepository(id: string, url: string, options?: MavenRepositoryOptions): void;
330
}
331

332
interface MavenDependencyOptions {
333
  /** Dependency scope (compile, test, runtime, etc.) */
334
  scope?: string;
335
  /** Dependency type */
336
  type?: string;
337
  /** Optional dependency */
338
  optional?: boolean;
339
  /** Exclusions */
340
  exclusions?: Array<{
341
    groupId: string;
342
    artifactId: string;
343
  }>;
344
}
345

346
interface PomOptions {
347
  /** Group ID */
348
  groupId?: string;
349
  /** Artifact ID */
350
  artifactId?: string;
351
  /** Version */
352
  version?: string;
353
  /** Packaging type */
354
  packaging?: string;
355
  /** Project description */
356
  description?: string;
357
}
358
```
359

360
**Java Dependencies Example:**
361

362
```typescript
363
import { JavaProject } from "projen";
364

365
const project = new JavaProject({
366
  name: "my-java-project",
367
  groupId: "com.example",
368
  artifactId: "my-java-project",
369
  version: "1.0.0",
370
});
371

372
// Add dependencies
373
project.pom.addDependency("org.springframework", "spring-core", "5.3.22");
374
project.pom.addDependency("org.slf4j", "slf4j-api", "1.7.36");
375

376
// Add test dependencies
377
project.pom.addTestDependency("junit", "junit", "4.13.2");
378
project.pom.addTestDependency("org.mockito", "mockito-core", "4.6.1");
379

380
// Add Maven plugins
381
project.pom.addPlugin("org.apache.maven.plugins", "maven-compiler-plugin", "3.8.1", {
382
  configuration: {
383
    source: "11",
384
    target: "11",
385
  },
386
});
387

388
// Add custom repository
389
project.pom.addRepository("central", "https://repo1.maven.org/maven2/");
390
```
391

392
### Dependency Upgrades
393

394
Automated dependency upgrade management.
395

396
```typescript { .api }
397
/**
398
 * Automated dependency upgrades for Node.js projects
399
 * Creates workflows to keep dependencies up to date
400
 */
401
class UpgradeDependencies extends Component {
402
  constructor(project: NodeProject, options?: UpgradeDependenciesOptions);
403
}
404

405
interface UpgradeDependenciesOptions {
406
  /** Upgrade workflow name */
407
  workflowName?: string;
408
  /** Upgrade schedule (cron expression) */
409
  schedule?: string;
410
  /** Include development dependencies */
411
  include?: string[];
412
  /** Exclude specific dependencies */
413
  exclude?: string[];
414
  /** Target branch for upgrade PRs */
415
  targetBranch?: string;
416
}
417
```
418

419
## Types
420

421
### Dependency-Related Types
422

423
```typescript { .api }
424
interface AuthorOptions {
425
  name: string;
426
  email?: string;
427
  url?: string;
428
  organization?: boolean;
429
}
430

431
interface RepositoryOptions {
432
  type: string;
433
  url: string;
434
  directory?: string;
435
}
436

437
interface BugsOptions {
438
  url?: string;
439
  email?: string;
440
}
441

442
interface MavenPluginOptions {
443
  /** Plugin configuration */
444
  configuration?: Record<string, any>;
445
  /** Plugin executions */
446
  executions?: Array<{
447
    id?: string;
448
    phase?: string;
449
    goals: string[];
450
    configuration?: Record<string, any>;
451
  }>;
452
}
453

454
interface MavenRepositoryOptions {
455
  /** Repository layout */
456
  layout?: string;
457
  /** Repository releases policy */
458
  releases?: {
459
    enabled?: boolean;
460
    updatePolicy?: string;
461
  };
462
  /** Repository snapshots policy */
463
  snapshots?: {
464
    enabled?: boolean;
465
    updatePolicy?: string;
466
  };
467
}
468
```