0
# @schematics/angular
1

2
@schematics/angular provides a comprehensive collection of Angular schematics (code generators) for creating and scaffolding Angular applications, components, services, and other constructs. This package serves as the foundation for Angular CLI's code generation capabilities, offering standardized templates and automated code creation that follows Angular best practices.
3

4
## Package Information
5

6
- **Package Name**: @schematics/angular
7
- **Package Type**: npm  
8
- **Language**: TypeScript
9
- **Installation**: `npm install @schematics/angular` or `ng add @schematics/angular`
10

11
## Core Imports
12

13
```typescript
14
import { Rule, Tree, SchematicContext } from '@angular-devkit/schematics';
15
```
16

17
For utility functions:
18

19
```typescript
20
import { 
21
  readWorkspace, 
22
  updateWorkspace,
23
  addDependency,
24
  DependencyType
25
} from '@schematics/angular/utility';
26
```
27

28
For CommonJS (not recommended):
29

30
```javascript
31
const { readWorkspace, updateWorkspace } = require('@schematics/angular/utility');
32
```
33

34
## Basic Usage
35

36
```typescript
37
import { Rule, Tree, SchematicContext } from '@angular-devkit/schematics';
38
import { readWorkspace, updateWorkspace } from '@schematics/angular/utility';
39

40
// Example schematic rule
41
export function myCustomSchematic(): Rule {
42
  return async (tree: Tree, context: SchematicContext) => {
43
    // Read Angular workspace configuration
44
    const workspace = await readWorkspace(tree);
45
    
46
    // Modify workspace or generate files
47
    tree.create('new-file.ts', 'export const greeting = "Hello World";');
48
    
49
    // Update workspace if needed
50
    return updateWorkspace((workspace) => {
51
      // Workspace modifications
52
    });
53
  };
54
}
55
```
56

57
## Architecture
58

59
@schematics/angular is built around several key components:
60

61
- **Schematic Collection**: 24 schematics for generating Angular code (20 public + 4 hidden/internal)
62
- **Utility Libraries**: Comprehensive functions for workspace management, AST manipulation, and file operations
63
- **Schema System**: JSON Schema-based configuration for all schematics with TypeScript type generation
64
- **Migration System**: 6 migration schematics for seamless Angular version upgrades and breaking change handling
65
- **Template Engine**: File template system with variable substitution and conditional generation
66

67
## Capabilities
68

69
### Schematic Generators
70

71
Code generation schematics for creating Angular applications and components. These are the primary entry points used by Angular CLI commands like `ng generate component`.
72

73
```typescript { .api }
74
// Main schematic factory interface
75
type SchematicFactory<T> = (options: T) => Rule;
76

77
// Core generator schematics
78
declare const application: SchematicFactory<ApplicationSchema>;
79
declare const component: SchematicFactory<ComponentSchema>;  
80
declare const service: SchematicFactory<ServiceSchema>;
81
declare const module: SchematicFactory<ModuleSchema>;
82
```
83

84
[Schematics](./schematics.md)
85

86
### Workspace Utilities
87

88
Utilities for reading, modifying, and managing Angular workspace configurations and project structures.
89

90
```typescript { .api }
91
function readWorkspace(tree: Tree, path?: string): Promise<WorkspaceDefinition>;
92
function updateWorkspace(updater: (workspace: WorkspaceDefinition) => void | PromiseLike<void>): Rule;
93
function writeWorkspace(workspace: WorkspaceDefinition, tree: Tree, path?: string): void;
94

95
interface WorkspaceDefinition {
96
  projects: Map<string, ProjectDefinition>;
97
  extensions: Record<string, JsonValue>;
98
}
99

100
interface ProjectDefinition {
101
  root: string;
102
  sourceRoot?: string;
103
  targets: Map<string, TargetDefinition>;
104
  extensions: Record<string, JsonValue>;
105
}
106
```
107

108
[Workspace Utilities](./workspace-utilities.md)
109

110
### Dependency Management
111

112
Functions for managing package.json dependencies within schematics, including adding, removing, and modifying npm packages.
113

114
```typescript { .api }
115
function addDependency(options: AddDependencyOptions): Rule;
116

117
interface AddDependencyOptions {
118
  type: DependencyType;
119
  name: string;
120
  version: string;
121
  registry?: string;
122
  installBehavior?: InstallBehavior;
123
  existingBehavior?: ExistingBehavior;
124
}
125

126
enum DependencyType {
127
  Default = 'dependencies',
128
  Dev = 'devDependencies', 
129
  Peer = 'peerDependencies'
130
}
131
```
132

133
[Dependency Management](./dependency-management.md)
134

135
### AST Manipulation
136

137
Utilities for parsing, analyzing, and modifying TypeScript Abstract Syntax Trees (AST) to programmatically update Angular code. These are not exported from the main utility index and must be imported directly.
138

139
```typescript { .api }
140
// Import from specific utility modules
141
import { findNode } from '@schematics/angular/utility/ast-utils';
142
import { addImportToModule } from '@schematics/angular/utility/ast-utils';
143
import { Change } from '@schematics/angular/utility/change';
144
```
145

146
[AST Utilities](./ast-utilities.md)
147

148
### Standalone Application Support
149

150
Utilities for working with Angular's standalone components and bootstrap configuration, supporting the modern Angular application architecture.
151

152
```typescript { .api }
153
function addRootImport(options: AddRootImportOptions): Rule;
154
function addRootProvider(options: AddRootProviderOptions): Rule;
155

156
interface AddRootImportOptions {
157
  import: string;
158
  from: string;
159
  project?: string;
160
}
161

162
interface AddRootProviderOptions {
163
  expression: string;
164
  import?: string;
165
  from?: string;
166
  project?: string;
167
}
168
```
169

170
[Standalone Utilities](./standalone-utilities.md)
171

172
## Types
173

174
### Core Types
175

176
```typescript { .api }
177
// Re-exported from @angular-devkit/schematics
178
type Rule = (tree: Tree, context: SchematicContext) => Tree | Observable<Tree> | Rule | Promise<Rule | Tree | Observable<Tree>> | void;
179

180
interface Tree {
181
  exists(path: string): boolean;
182
  read(path: string): Buffer | null;
183
  readText(path: string): string;
184
  create(path: string, content: Buffer | string): void;
185
  overwrite(path: string, content: Buffer | string): void;
186
  rename(from: string, to: string): void;
187
  delete(path: string): void;
188
}
189

190
interface SchematicContext {
191
  readonly schematic: Schematic<any, any>;
192
  readonly strategy: MergeStrategy;
193
  readonly interactive: boolean;
194
  addTask<T>(task: TaskConfiguration<T>, dependencies?: Array<TaskId>): TaskId;
195
}
196
```
197

198
### Workspace Types
199

200
```typescript { .api }
201
interface TargetDefinition {
202
  builder: string;
203
  defaultConfiguration?: string;
204
  configurations?: Record<string, Record<string, JsonValue>>;
205
  options?: Record<string, JsonValue>;
206
}
207

208
enum ProjectType {
209
  Application = 'application',
210
  Library = 'library'
211
}
212

213
enum AngularBuilder {
214
  Application = '@angular-devkit/build-angular:application',
215
  Browser = '@angular-devkit/build-angular:browser',
216
  DevServer = '@angular-devkit/build-angular:dev-server',
217
  Karma = '@angular-devkit/build-angular:karma',
218
  Protractor = '@angular-devkit/build-angular:protractor',
219
  Extract = '@angular-devkit/build-angular:extract-i18n',
220
  NgPackagr = 'ng-packagr:build'
221
}
222
```
223

224
### Additional Types
225

226
```typescript { .api }
227
// Location type for file generation
228
interface Location {
229
  name: string;
230
  path: string;
231
}
232

233
// Module options for AST utilities
234
interface ModuleOptions {
235
  module?: string;
236
  name: string;
237
  path?: string;
238
  flat?: boolean;
239
}
240

241
// Generate from files options
242
interface GenerateFromFilesOptions {
243
  templates?: string;
244
  destination?: string;
245
}
246

247
// Latest versions configuration
248
interface LatestVersions {
249
  Angular: string;
250
  DevkitBuildAngular: string;
251
  DevkitSchematics: string;
252
  AngularCli: string;
253
  RxJs: string;
254
  TypeScript: string;
255
  ZoneJs: string;
256
  AngularPWA: string;
257
  [packageName: string]: string;
258
}
259
```
260

261
## Additional Utilities
262

263
### Direct Import APIs
264

265
Some utilities are not exported from the main utility index but can be imported directly:
266

267
```typescript { .api }
268
// AST manipulation utilities (not in main utility exports)
269
import { 
270
  findNode,
271
  findNodes,
272
  getSourceNodes,
273
  addImportToModule,
274
  addDeclarationToModule,
275
  addProviderToModule,
276
  insertImport,
277
  Change,
278
  InsertChange,
279
  RemoveChange,
280
  ReplaceChange,
281
  applyToUpdateRecorder
282
} from '@schematics/angular/utility/ast-utils';
283

284
// Package.json manipulation (not in main utility exports)
285
import { 
286
  addPackageJsonDependency,
287
  getPackageJsonDependency,
288
  removePackageJsonDependency,
289
  NodeDependency,
290
  NodeDependencyType
291
} from '@schematics/angular/utility/dependencies';
292

293
// Version information
294
import { latestVersions } from '@schematics/angular/utility/latest-versions';
295

296
// Project utilities  
297
import { 
298
  getProject,
299
  isWorkspaceProject,
300
  buildDefaultPath,
301
  createDefaultPath,
302
  allWorkspaceTargets,
303
  allTargetOptions
304
} from '@schematics/angular/utility/workspace';
305

306
// Path utilities
307
import { 
308
  relativePathToWorkspaceRoot,
309
  buildRelativePath
310
} from '@schematics/angular/utility/paths';
311

312
// Validation utilities
313
import { 
314
  validateHtmlSelector,
315
  validateClassName,
316
  validateName
317
} from '@schematics/angular/utility/validation';
318

319
// Test utilities
320
import { 
321
  SchematicTestRunner,
322
  UnitTestTree
323
} from '@schematics/angular/utility/test';
324
```