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
```