0
# Workspace Configuration
1

2
Comprehensive workspace and project configuration management for reading, creating, updating, and organizing Nx workspaces and projects.
3

4
## Capabilities
5

6
### Project Configuration Management
7

8
Core functions for managing individual project configurations within an Nx workspace.
9

10
```typescript { .api }
11
/**
12
 * Add a new project configuration to the workspace
13
 * @param tree - File system tree
14
 * @param projectName - Name of the project
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 configuration
25
 * @param tree - File system tree
26
 * @param projectName - Name of the project
27
 * @returns Project configuration object
28
 */
29
function readProjectConfiguration(
30
  tree: Tree,
31
  projectName: string
32
): ProjectConfiguration;
33

34
/**
35
 * Update an existing project configuration
36
 * @param tree - File system tree
37
 * @param projectName - Name of the project  
38
 * @param projectConfiguration - Updated project configuration
39
 */
40
function updateProjectConfiguration(
41
  tree: Tree,
42
  projectName: string,
43
  projectConfiguration: ProjectConfiguration
44
): void;
45

46
/**
47
 * Remove a project configuration from the workspace
48
 * @param tree - File system tree
49
 * @param projectName - Name of the project to remove
50
 */
51
function removeProjectConfiguration(
52
  tree: Tree,
53
  projectName: string
54
): void;
55

56
/**
57
 * Get all projects in the workspace
58
 * @param tree - File system tree
59
 * @returns Map of project names to configurations
60
 */
61
function getProjects(tree: Tree): Map<string, ProjectConfiguration>;
62
```
63

64
**Usage Examples:**
65

66
```typescript
67
import {
68
  Tree,
69
  addProjectConfiguration,
70
  readProjectConfiguration,
71
  updateProjectConfiguration,
72
  getProjects
73
} from "@nx/devkit";
74

75
export default function myGenerator(tree: Tree, options: { name: string }) {
76
  // Add a new library project
77
  addProjectConfiguration(tree, options.name, {
78
    root: `libs/${options.name}`,
79
    projectType: "library",
80
    sourceRoot: `libs/${options.name}/src`,
81
    targets: {
82
      build: {
83
        executor: "@nx/js:tsc",
84
        outputs: [`{workspaceRoot}/dist/libs/${options.name}`],
85
        options: {
86
          main: `libs/${options.name}/src/index.ts`,
87
          tsConfig: `libs/${options.name}/tsconfig.lib.json`,
88
        },
89
      },
90
      test: {
91
        executor: "@nx/jest:jest",
92
        outputs: [`{workspaceRoot}/coverage/libs/${options.name}`],
93
        options: {
94
          jestConfig: `libs/${options.name}/jest.config.ts`,
95
        },
96
      },
97
    },
98
  });
99

100
  // Read existing project configuration
101
  const existingProject = readProjectConfiguration(tree, "my-app");
102
  
103
  // Update project to add a new target
104
  updateProjectConfiguration(tree, "my-app", {
105
    ...existingProject,
106
    targets: {
107
      ...existingProject.targets,
108
      lint: {
109
        executor: "@nx/linter:eslint",
110
        options: {
111
          lintFilePatterns: [`${existingProject.root}/**/*.ts`],
112
        },
113
      },
114
    },
115
  });
116

117
  // Get all projects
118
  const allProjects = getProjects(tree);
119
  console.log(`Workspace has ${allProjects.size} projects`);
120
}
121
```
122

123
### Nx Configuration Management
124

125
Functions for managing the main Nx workspace configuration (nx.json).
126

127
```typescript { .api }
128
/**
129
 * Read the nx.json configuration
130
 * @param tree - File system tree
131
 * @returns Nx configuration object or null if not found
132
 */
133
function readNxJson(tree: Tree): NxJsonConfiguration | null;
134

135
/**
136
 * Update the nx.json configuration
137
 * @param tree - File system tree
138
 * @param nxJsonConfiguration - Updated Nx configuration
139
 */
140
function updateNxJson(
141
  tree: Tree,
142
  nxJsonConfiguration: NxJsonConfiguration
143
): void;
144
```
145

146
**Usage Examples:**
147

148
```typescript
149
import { Tree, readNxJson, updateNxJson } from "@nx/devkit";
150

151
export default function myGenerator(tree: Tree) {
152
  // Read current nx.json
153
  const nxJson = readNxJson(tree);
154
  
155
  if (nxJson) {
156
    // Update nx.json to add a new named input
157
    updateNxJson(tree, {
158
      ...nxJson,
159
      namedInputs: {
160
        ...nxJson.namedInputs,
161
        production: [
162
          "default",
163
          "!{projectRoot}/**/*.spec.ts",
164
          "!{projectRoot}/**/*.test.ts",
165
        ],
166
      },
167
      targetDefaults: {
168
        ...nxJson.targetDefaults,
169
        build: {
170
          ...nxJson.targetDefaults?.build,
171
          inputs: ["production", "^production"],
172
        },
173
      },
174
    });
175
  }
176
}
177
```
178

179
### Workspace Layout
180

181
Functions for managing workspace directory structure and layout preferences.
182

183
```typescript { .api }
184
/**
185
 * Get the current workspace layout configuration
186
 * @param tree - File system tree
187
 * @returns Workspace layout configuration
188
 */
189
function getWorkspaceLayout(tree: Tree): {
190
  appsDir: string;
191
  libsDir: string;
192
  standaloneAsDefault: boolean;
193
};
194

195
/**
196
 * Extract layout directory information from a path
197
 * @param directory - Directory path to analyze
198
 * @returns Layout directory information
199
 */
200
function extractLayoutDirectory(directory?: string): {
201
  layoutDirectory: string | null;
202
  projectDirectory?: string;
203
};
204

205
/**
206
 * Get workspace layout from configuration
207
 * @returns Default workspace layout object
208
 */
209
const workspaceLayout: {
210
  appsDir: string;
211
  libsDir: string;
212
};
213
```
214

215
**Usage Examples:**
216

217
```typescript
218
import { Tree, getWorkspaceLayout, extractLayoutDirectory } from "@nx/devkit";
219

220
export default function myGenerator(tree: Tree, options: { directory?: string }) {
221
  // Get workspace layout
222
  const layout = getWorkspaceLayout(tree);
223
  console.log(`Apps directory: ${layout.appsDir}`);
224
  console.log(`Libs directory: ${layout.libsDir}`);
225
  
226
  // Extract layout info from user input
227
  const { layoutDirectory, projectDirectory } = extractLayoutDirectory(
228
    options.directory
229
  );
230
  
231
  const finalDirectory = layoutDirectory 
232
    ? `${layout.libsDir}/${layoutDirectory}/${projectDirectory}`
233
    : `${layout.libsDir}/${projectDirectory}`;
234
}
235
```
236

237
## Configuration Types
238

239
### Project Configuration
240

241
```typescript { .api }
242
interface ProjectConfiguration {
243
  /** Project name (optional, inferred from key in projects map) */
244
  name?: string;
245
  /** Root directory of the project relative to workspace root */
246
  root: string;
247
  /** Source root directory relative to workspace root */
248
  sourceRoot?: string;
249
  /** Type of project */
250
  projectType?: ProjectType;
251
  /** Available targets/tasks for this project */
252
  targets?: Record<string, TargetConfiguration>;
253
  /** Tags for categorizing and selecting projects */
254
  tags?: string[];
255
  /** Projects this project implicitly depends on */
256
  implicitDependencies?: string[];
257
  /** Default generator options */
258
  generators?: Record<string, any>;
259
  /** Named input definitions for targets */
260
  namedInputs?: Record<string, (string | InputDefinition)[]>;
261
}
262

263
type ProjectType = "application" | "library";
264

265
interface TargetConfiguration<T = any> {
266
  /** Executor to run for this target */
267
  executor?: string;
268
  /** Default options for the target */
269
  options?: T;
270
  /** Different configurations for the target */
271
  configurations?: Record<string, Partial<T>>;
272
  /** Default configuration to use */
273
  defaultConfiguration?: string;
274
  /** Other targets this target depends on */
275
  dependsOn?: TargetDependencyConfig[];
276
  /** Input files that affect this target */
277
  inputs?: (InputDefinition | string)[];
278
  /** Output files/directories produced by this target */
279
  outputs?: string[];
280
}
281

282
interface TargetDependencyConfig {
283
  /** Target name */
284
  target: string;
285
  /** Projects to run the target on */
286
  projects?: "self" | "dependencies" | string[];
287
  /** Configuration parameters */
288
  params?: "forward" | Record<string, any>;
289
}
290
```
291

292
### Nx Configuration
293

294
```typescript { .api }
295
interface NxJsonConfiguration<T = "*" | string[]> {
296
  /** Nx configuration version */
297
  version?: number;
298
  /** Implicit dependencies configuration */
299
  implicitDependencies?: ImplicitDependencyEntry<T>;
300
  /** Affected command configuration */
301
  affected?: NxAffectedConfig;
302
  /** Workspace layout preferences */
303
  workspaceLayout?: {
304
    appsDir?: string;
305
    libsDir?: string;
306
  };
307
  /** Task runner configuration */
308
  tasksRunnerOptions?: {
309
    [tasksRunnerName: string]: {
310
      runner?: string;
311
      options?: any;
312
    };
313
  };
314
  /** Default target configurations */
315
  targetDefaults?: TargetDefaults;
316
  /** Named input definitions */
317
  namedInputs?: { [inputName: string]: (string | InputDefinition)[] };
318
  /** Generator defaults */
319
  generators?: Record<string, Record<string, any>>;
320
  /** CLI configuration */
321
  cli?: {
322
    packageManager?: PackageManager;
323
    defaultCollection?: string;
324
  };
325
  /** Plugin configurations */
326
  plugins?: PluginConfiguration[];
327
  /** Default base branch for affected calculations */
328
  defaultBase?: string;
329
  /** Nx Cloud configuration */
330
  nxCloudAccessToken?: string;
331
  /** Remote cache configuration */
332
  tasksRunnerOptions?: Record<string, any>;
333
}
334

335
interface NxAffectedConfig {
336
  /** Default base branch */
337
  defaultBase?: string;
338
}
339

340
type TargetDefaults = Record<string, Partial<TargetConfiguration>>;
341

342
interface ImplicitDependencyEntry<T = "*" | string[]> {
343
  [key: string]: T | ImplicitJsonSubsetDependency<T>;
344
}
345

346
interface ImplicitJsonSubsetDependency<T = "*" | string[]> {
347
  [key: string]: T;
348
}
349
```
350

351
### Workspace Configuration
352

353
```typescript { .api }
354
interface WorkspaceJsonConfiguration extends ProjectsConfigurations {
355
  /** Workspace configuration version */
356
  version: number;
357
}
358

359
interface ProjectsConfigurations {
360
  /** Configuration version */
361
  version: number;
362
  /** Map of project names to configurations */
363
  projects: Record<string, ProjectConfiguration>;
364
}
365

366
interface Workspace {
367
  /** Workspace version */
368
  version: number;
369
  /** Map of project names to configurations */
370
  projects: Record<string, ProjectConfiguration>;
371
  /** Nx configuration */
372
  cli?: {
373
    defaultCollection?: string;
374
    packageManager?: PackageManager;
375
  };
376
}
377
```