0
# Workspace Utilities
1

2
Utilities for reading, modifying, and managing Angular workspace configurations and project structures. These functions provide a high-level API for working with `angular.json` and project metadata.
3

4
## Capabilities
5

6
### Workspace Reading
7

8
Functions for reading Angular workspace configuration from `angular.json` files.
9

10
```typescript { .api }
11
/**
12
 * Reads the Angular workspace configuration from angular.json
13
 * @param tree - The virtual file system tree
14
 * @param path - Optional path to workspace file (defaults to '/angular.json')
15
 * @returns Promise resolving to workspace definition
16
 */
17
function readWorkspace(tree: Tree, path?: string): Promise<WorkspaceDefinition>;
18

19
/**
20
 * Legacy function name, alias for readWorkspace
21
 * @deprecated Use readWorkspace instead
22
 */
23
function getWorkspace(tree: Tree, path?: string): Promise<WorkspaceDefinition>;
24
```
25

26
**Usage Example:**
27

28
```typescript
29
import { readWorkspace } from '@schematics/angular/utility';
30

31
export function mySchematic(): Rule {
32
  return async (tree: Tree) => {
33
    const workspace = await readWorkspace(tree);
34
    
35
    // Access projects
36
    const defaultProject = workspace.projects.get('my-app');
37
    console.log('Project root:', defaultProject?.root);
38
    
39
    return tree;
40
  };
41
}
42
```
43

44
### Workspace Writing
45

46
Functions for updating and writing workspace configuration changes.
47

48
```typescript { .api }
49
/**
50
 * Updates workspace configuration using an updater function
51
 * @param updater - Function that receives workspace and can modify it
52
 * @returns Rule that applies the workspace changes
53
 */
54
function updateWorkspace(
55
  updater: (workspace: WorkspaceDefinition) => void | PromiseLike<void>
56
): Rule;
57

58
/**
59
 * Writes workspace definition to angular.json file
60
 * @param workspace - Workspace definition to write
61
 * @param tree - Virtual file system tree
62
 * @param path - Optional path to workspace file (defaults to '/angular.json')
63
 */
64
function writeWorkspace(
65
  workspace: WorkspaceDefinition, 
66
  tree: Tree, 
67
  path?: string
68
): void;
69
```
70

71
**Usage Example:**
72

73
```typescript
74
import { updateWorkspace } from '@schematics/angular/utility';
75

76
export function addBuildTarget(): Rule {
77
  return updateWorkspace((workspace) => {
78
    const project = workspace.projects.get('my-app');
79
    if (project) {
80
      project.targets.set('custom-build', {
81
        builder: '@angular-devkit/build-angular:browser',
82
        options: {
83
          outputPath: 'dist/custom'
84
        }
85
      });
86
    }
87
  });
88
}
89
```
90

91
### Project Utilities
92

93
Functions for working with individual projects within a workspace.
94

95
```typescript { .api }
96
/**
97
 * Gets a project from workspace by name, throws if not found
98
 * @param workspace - The workspace definition
99
 * @param projectName - Name of the project to retrieve
100
 * @returns Project definition
101
 * @throws Error if project is not found
102
 */
103
function getProject(
104
  workspace: WorkspaceDefinition, 
105
  projectName: string
106
): ProjectDefinition;
107

108
/**
109
 * Checks if a project is a workspace project (not external)
110
 * @param project - Project definition to check
111
 * @returns True if project is a workspace project
112
 */
113
function isWorkspaceProject(project: ProjectDefinition): boolean;
114

115
/**
116
 * Checks if workspace follows the workspace schema format
117
 * @param workspace - Workspace to validate
118
 * @returns True if workspace is valid
119
 */
120
function isWorkspaceSchema(workspace: WorkspaceDefinition): boolean;
121
```
122

123
### Path Utilities
124

125
Functions for working with project paths and building relative paths.
126

127
```typescript { .api }
128
/**
129
 * Builds the default path for generating files within a project
130
 * @param project - Project definition
131
 * @returns Default path string (typically sourceRoot + '/app')
132
 */
133
function buildDefaultPath(project: ProjectDefinition): string;
134

135
/**
136
 * Builds a relative path from project root to workspace root
137
 * @param projectRoot - Project root directory
138
 * @returns Relative path string
139
 */
140
function relativePathToWorkspaceRoot(projectRoot: string): string;
141

142
/**
143
 * Builds a relative path between two absolute paths
144
 * @param from - Source path
145
 * @param to - Target path  
146
 * @returns Relative path string
147
 */
148
function buildRelativePath(from: string, to: string): string;
149
```
150

151
**Usage Example:**
152

153
```typescript
154
import { buildDefaultPath, getProject } from '@schematics/angular/utility';
155

156
export function generateComponent(): Rule {
157
  return async (tree: Tree) => {
158
    const workspace = await readWorkspace(tree);
159
    const project = getProject(workspace, 'my-app');
160
    
161
    // Get default path: /src/app
162
    const defaultPath = buildDefaultPath(project);
163
    
164
    // Create component in default location
165
    tree.create(`${defaultPath}/my-component.ts`, componentContent);
166
    
167
    return tree;
168
  };
169
}
170
```
171

172
### Workspace Host
173

174
Low-level host implementation for direct workspace file operations.
175

176
```typescript { .api }
177
/**
178
 * A WorkspaceHost implementation backed by a Schematics Tree
179
 * Provides file system operations for workspace manipulation
180
 */
181
class TreeWorkspaceHost implements workspaces.WorkspaceHost {
182
  constructor(tree: Tree);
183
  
184
  /**
185
   * Reads file content as string
186
   * @param path - File path to read
187
   * @returns Promise resolving to file content
188
   */
189
  readFile(path: string): Promise<string>;
190
  
191
  /**
192
   * Writes file content
193
   * @param path - File path to write
194
   * @param data - Content to write
195
   */
196
  writeFile(path: string, data: string): Promise<void>;
197
  
198
  /**
199
   * Checks if path is a directory
200
   * @param path - Path to check
201
   * @returns Promise resolving to boolean
202
   */
203
  isDirectory(path: string): Promise<boolean>;
204
  
205
  /**
206
   * Checks if path is a file
207
   * @param path - Path to check
208
   * @returns Promise resolving to boolean
209
   */
210
  isFile(path: string): Promise<boolean>;
211
}
212
```
213

214
## Types
215

216
### Core Workspace Types
217

218
```typescript { .api }
219
interface WorkspaceDefinition {
220
  /** Map of project names to project definitions */
221
  projects: Map<string, ProjectDefinition>;
222
  /** Additional workspace-level configuration */
223
  extensions: Record<string, JsonValue>;
224
  /** Default project name */
225
  defaultProject?: string;
226
  /** Workspace version */
227
  version: number;
228
  /** New project root directory */
229
  newProjectRoot?: string;
230
  /** CLI configuration */
231
  cli?: Record<string, JsonValue>;
232
  /** Schematics configuration */
233
  schematics?: Record<string, JsonValue>;
234
  /** Architect configuration */
235
  architect?: Record<string, JsonValue>;
236
}
237

238
interface ProjectDefinition {
239
  /** Project root directory relative to workspace */
240
  root: string;
241
  /** Source root directory relative to workspace */
242
  sourceRoot?: string;
243
  /** Project type (application or library) */
244
  projectType?: ProjectType;
245
  /** Map of target names to target definitions */
246
  targets: Map<string, TargetDefinition>;
247
  /** Additional project-level configuration */
248
  extensions: Record<string, JsonValue>;
249
  /** Project prefix for generated selectors */
250
  prefix?: string;
251
  /** Schematics configuration for this project */
252
  schematics?: Record<string, JsonValue>;
253
  /** Architect configuration for this project */
254
  architect?: Record<string, JsonValue>;
255
}
256

257
interface TargetDefinition {
258
  /** Builder to use for this target */
259
  builder: string;
260
  /** Default configuration to use */
261
  defaultConfiguration?: string;
262
  /** Named configurations */
263
  configurations?: Record<string, Record<string, JsonValue>>;
264
  /** Default options */
265
  options?: Record<string, JsonValue>;
266
}
267

268
enum ProjectType {
269
  Application = 'application',
270
  Library = 'library'
271
}
272
```
273

274
### Builder Definitions
275

276
```typescript { .api }
277
enum Builders {
278
  Application = '@angular-devkit/build-angular:application',
279
  Browser = '@angular-devkit/build-angular:browser',
280
  DevServer = '@angular-devkit/build-angular:dev-server',
281
  Karma = '@angular-devkit/build-angular:karma',
282
  Protractor = '@angular-devkit/build-angular:protractor',
283
  Extract = '@angular-devkit/build-angular:extract-i18n',
284
  NgPackagr = 'ng-packagr:build',
285
  Lint = '@angular-eslint/builder:lint'
286
}
287
```