0
# Project Configuration Management
1

2
APIs for managing workspace projects, reading and updating project configurations, and handling workspace-level settings. These functions provide programmatic access to project metadata, build targets, and workspace structure.
3

4
## Capabilities
5

6
### Project Configuration Functions
7

8
Core functions for managing individual project configurations.
9

10
```typescript { .api }
11
/**
12
 * Add a new project configuration to the workspace
13
 * @param tree - Virtual file system tree
14
 * @param projectName - Name of the project to add
15
 * @param projectConfiguration - Project configuration object
16
 */
17
function addProjectConfiguration(
18
  tree: Tree,
19
  projectName: string,
20
  projectConfiguration: ProjectConfiguration
21
): void;
22

23
/**
24
 * Read an existing project's configuration
25
 * @param tree - Virtual file system tree
26
 * @param projectName - Name of the project to read
27
 * @returns Project configuration object
28
 */
29
function readProjectConfiguration(tree: Tree, projectName: string): ProjectConfiguration;
30

31
/**
32
 * Update an existing project's configuration
33
 * @param tree - Virtual file system tree
34
 * @param projectName - Name of the project to update
35
 * @param projectConfiguration - Updated project configuration
36
 */
37
function updateProjectConfiguration(
38
  tree: Tree,
39
  projectName: string,
40
  projectConfiguration: ProjectConfiguration
41
): void;
42

43
/**
44
 * Remove a project configuration from the workspace
45
 * @param tree - Virtual file system tree
46
 * @param projectName - Name of the project to remove
47
 */
48
function removeProjectConfiguration(tree: Tree, projectName: string): void;
49

50
/**
51
 * Get all projects in the workspace
52
 * @param tree - Virtual file system tree
53
 * @returns Map of project names to configurations
54
 */
55
function getProjects(tree: Tree): Map<string, ProjectConfiguration>;
56
```
57

58
**Usage Examples:**
59

60
```typescript
61
import { 
62
  Tree, 
63
  addProjectConfiguration, 
64
  readProjectConfiguration,
65
  updateProjectConfiguration,
66
  ProjectConfiguration 
67
} from "@nrwl/devkit";
68

69
function manageProjects(tree: Tree) {
70
  // Add a new library project
71
  const libraryConfig: ProjectConfiguration = {
72
    root: 'libs/my-lib',
73
    projectType: 'library',
74
    sourceRoot: 'libs/my-lib/src',
75
    targets: {
76
      build: {
77
        executor: '@nx/js:tsc',
78
        options: {
79
          outputPath: 'dist/libs/my-lib',
80
          main: 'libs/my-lib/src/index.ts',
81
          tsConfig: 'libs/my-lib/tsconfig.lib.json'
82
        }
83
      },
84
      test: {
85
        executor: '@nx/jest:jest',
86
        options: {
87
          jestConfig: 'libs/my-lib/jest.config.ts'
88
        }
89
      }
90
    },
91
    tags: ['scope:shared', 'type:util']
92
  };
93
  
94
  addProjectConfiguration(tree, 'my-lib', libraryConfig);
95
  
96
  // Read and modify existing project
97
  const existingProject = readProjectConfiguration(tree, 'my-lib');
98
  existingProject.targets!.lint = {
99
    executor: '@nx/linter:eslint',
100
    options: {
101
      lintFilePatterns: ['libs/my-lib/**/*.ts']
102
    }
103
  };
104
  
105
  updateProjectConfiguration(tree, 'my-lib', existingProject);
106
  
107
  // List all projects
108
  const projects = getProjects(tree);
109
  for (const [name, config] of projects) {
110
    console.log(`Project: ${name}, Type: ${config.projectType}`);
111
  }
112
}
113
```
114

115
### Workspace Configuration Functions
116

117
Functions for managing workspace-level Nx configuration.
118

119
```typescript { .api }
120
/**
121
 * Read the nx.json configuration file
122
 * @param tree - Virtual file system tree
123
 * @returns Nx configuration object
124
 */
125
function readNxJson(tree: Tree): NxJsonConfiguration | null;
126

127
/**
128
 * Update the nx.json configuration file
129
 * @param tree - Virtual file system tree
130
 * @param nxJson - Updated Nx configuration
131
 */
132
function updateNxJson(tree: Tree, nxJson: NxJsonConfiguration): void;
133

134
/**
135
 * Get workspace layout configuration
136
 * @param tree - Virtual file system tree
137
 * @returns Workspace layout information
138
 */
139
function getWorkspaceLayout(tree: Tree): {
140
  appsDir: string;
141
  libsDir: string;
142
  npmScope?: string;
143
};
144

145
/**
146
 * Extract directory layout information
147
 * @param nxJson - Nx configuration object
148
 * @returns Layout directory configuration
149
 */
150
function extractLayoutDirectory(nxJson?: NxJsonConfiguration): {
151
  appsDir: string;
152
  libsDir: string;
153
};
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
import { 
160
  Tree, 
161
  readNxJson, 
162
  updateNxJson, 
163
  getWorkspaceLayout,
164
  NxJsonConfiguration 
165
} from "@nrwl/devkit";
166

167
function configureWorkspace(tree: Tree) {
168
  // Read current nx.json
169
  const nxJson = readNxJson(tree);
170
  
171
  if (nxJson) {
172
    // Add target defaults
173
    nxJson.targetDefaults = {
174
      ...nxJson.targetDefaults,
175
      build: {
176
        dependsOn: ['^build'],
177
        inputs: ['production', '^production']
178
      }
179
    };
180
    
181
    // Add named inputs
182
    nxJson.namedInputs = {
183
      ...nxJson.namedInputs,
184
      production: [
185
        'default',
186
        '!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)?(.snap)',
187
        '!{projectRoot}/tsconfig.spec.json',
188
        '!{projectRoot}/jest.config.[jt]s'
189
      ]
190
    };
191
    
192
    updateNxJson(tree, nxJson);
193
  }
194
  
195
  // Get workspace layout
196
  const layout = getWorkspaceLayout(tree);
197
  console.log(`Apps directory: ${layout.appsDir}`);
198
  console.log(`Libs directory: ${layout.libsDir}`);
199
}
200
```
201

202
### Configuration Types
203

204
Core interfaces for project and workspace configuration.
205

206
```typescript { .api }
207
/**
208
 * Configuration for a single project
209
 */
210
interface ProjectConfiguration {
211
  /** Optional project name (usually inferred from directory structure) */
212
  name?: string;
213
  /** Root directory of the project relative to workspace root */
214
  root: string;
215
  /** Source root directory relative to workspace root */
216
  sourceRoot?: string;
217
  /** Type of project */
218
  projectType?: ProjectType;
219
  /** Build targets available for this project */
220
  targets?: Record<string, TargetConfiguration>;
221
  /** Tags for categorizing and filtering projects */
222
  tags?: string[];
223
  /** Explicit dependencies on other projects */
224
  implicitDependencies?: string[];
225
  /** Named inputs for this project */
226
  namedInputs?: Record<string, (InputDefinition | string)[]>;
227
  /** Additional metadata */
228
  metadata?: Record<string, any>;
229
}
230

231
/**
232
 * Project type classification
233
 */
234
type ProjectType = 'application' | 'library';
235

236
/**
237
 * Configuration for a build target
238
 */
239
interface TargetConfiguration<T = any> {
240
  /** Executor to run for this target */
241
  executor: string;
242
  /** Default options for the executor */
243
  options?: T;
244
  /** Named configurations with option overrides */
245
  configurations?: Record<string, Partial<T>>;
246
  /** Default configuration to use */
247
  defaultConfiguration?: string;
248
  /** Dependencies that must run before this target */
249
  dependsOn?: TargetDependencyConfig[];
250
  /** Input definitions for cache invalidation */
251
  inputs?: (InputDefinition | string)[];
252
  /** Output paths for caching */
253
  outputs?: string[];
254
  /** Whether to cache this target */
255
  cache?: boolean;
256
  /** Additional metadata */
257
  metadata?: Record<string, any>;
258
}
259

260
/**
261
 * Target dependency configuration
262
 */
263
interface TargetDependencyConfig {
264
  /** Target name */
265
  target: string;
266
  /** Project to run target on (defaults to current project) */
267
  projects?: string | string[];
268
  /** Configuration to use */
269
  params?: 'forward' | 'ignore' | Record<string, any>;
270
}
271

272
/**
273
 * Workspace-level Nx configuration
274
 */
275
interface NxJsonConfiguration {
276
  /** Configuration to extend */
277
  extends?: string;
278
  /** NPM scope for the workspace */
279
  npmScope?: string;
280
  /** Affected command configuration */
281
  affected?: NxAffectedConfig;
282
  /** Implicit dependencies between projects */
283
  implicitDependencies?: Record<string, string[] | '*'>;
284
  /** Default target configurations */
285
  targetDefaults?: TargetDefaults;
286
  /** CLI configuration */
287
  cli?: {
288
    defaultCollection?: string;
289
    packageManager?: PackageManager;
290
    analytics?: boolean;
291
  };
292
  /** Generator defaults */
293
  generators?: Record<string, any>;
294
  /** Task runner configuration */
295
  tasksRunnerOptions?: Record<string, any>;
296
  /** Named input definitions */
297
  namedInputs?: Record<string, (InputDefinition | string)[]>;
298
  /** Plugin configurations */
299
  plugins?: PluginConfiguration[];
300
  /** Maximum parallel processes */
301
  parallel?: number;
302
  /** Cache directory location */
303
  cacheDirectory?: string;
304
  /** Default base branch for affected calculations */
305
  defaultBase?: string;
306
  /** Nx Cloud access token */
307
  nxCloudAccessToken?: string;
308
  /** Whether to use the Nx daemon */
309
  useDaemonProcess?: boolean;
310
}
311

312
/**
313
 * Plugin configuration
314
 */
315
interface PluginConfiguration {
316
  plugin: string;
317
  options?: any;
318
}
319

320
/**
321
 * Input definition for caching
322
 */
323
interface InputDefinition {
324
  input?: string;
325
  projects?: string | string[];
326
  dependencies?: boolean;
327
}
328
```
329

330
**Usage Examples:**
331

332
```typescript
333
import { 
334
  ProjectConfiguration, 
335
  TargetConfiguration, 
336
  NxJsonConfiguration 
337
} from "@nrwl/devkit";
338

339
// Define a React application project
340
const reactAppConfig: ProjectConfiguration = {
341
  root: 'apps/my-app',
342
  projectType: 'application',
343
  sourceRoot: 'apps/my-app/src',
344
  targets: {
345
    build: {
346
      executor: '@nx/webpack:webpack',
347
      options: {
348
        outputPath: 'dist/apps/my-app',
349
        index: 'apps/my-app/src/index.html',
350
        main: 'apps/my-app/src/main.tsx'
351
      },
352
      configurations: {
353
        production: {
354
          fileReplacements: [
355
            {
356
              replace: 'apps/my-app/src/environments/environment.ts',
357
              with: 'apps/my-app/src/environments/environment.prod.ts'
358
            }
359
          ]
360
        }
361
      }
362
    },
363
    serve: {
364
      executor: '@nx/webpack:dev-server',
365
      options: {
366
        buildTarget: 'my-app:build'
367
      }
368
    }
369
  },
370
  tags: ['scope:app', 'type:web']
371
};
372
```