0
# Utilities
1

2
Utility functions in @nx/angular provide helper functionality for manipulating Angular code structures, adding imports, providers, and routes programmatically.
3

4
## Capabilities
5

6
### AST Manipulation Utilities
7

8
#### Module Import Functions
9

10
Functions for adding imports to Angular modules and components.
11

12
```typescript { .api }
13
/**
14
 * Add import to an Angular module
15
 * @param tree - Virtual file system tree
16
 * @param modulePath - Path to the module file
17
 * @param importName - Name of the import to add
18
 */
19
function addImportToModule(
20
  tree: Tree,
21
  modulePath: string,
22
  importName: string
23
): void;
24

25
/**
26
 * Add import to an Angular component
27
 * @param tree - Virtual file system tree
28
 * @param componentPath - Path to the component file
29
 * @param importName - Name of the import to add
30
 */
31
function addImportToComponent(
32
  tree: Tree,
33
  componentPath: string,
34
  importName: string
35
): void;
36

37
/**
38
 * Add import to an Angular directive
39
 * @param tree - Virtual file system tree
40
 * @param directivePath - Path to the directive file
41
 * @param importName - Name of the import to add
42
 */
43
function addImportToDirective(
44
  tree: Tree,
45
  directivePath: string,
46
  importName: string
47
): void;
48

49
/**
50
 * Add import to an Angular pipe
51
 * @param tree - Virtual file system tree
52
 * @param pipePath - Path to the pipe file
53
 * @param importName - Name of the import to add
54
 */
55
function addImportToPipe(
56
  tree: Tree,
57
  pipePath: string,
58
  importName: string
59
): void;
60
```
61

62
**Usage Example:**
63

64
```typescript
65
import { addImportToModule } from "@nx/angular/src/utils";
66
import { Tree } from "@nx/devkit";
67

68
// Add HttpClientModule to app.module.ts
69
addImportToModule(
70
  tree,
71
  "src/app/app.module.ts",
72
  "HttpClientModule"
73
);
74
```
75

76
#### Provider Management Functions
77

78
Functions for adding providers to various Angular configurations.
79

80
```typescript { .api }
81
/**
82
 * Add provider to bootstrapApplication call
83
 * @param tree - Virtual file system tree
84
 * @param filePath - Path to the main.ts file
85
 * @param provider - Provider to add
86
 */
87
function addProviderToBootstrapApplication(
88
  tree: Tree,
89
  filePath: string,
90
  provider: string
91
): void;
92

93
/**
94
 * Add provider to application configuration
95
 * @param tree - Virtual file system tree
96
 * @param filePath - Path to the app.config.ts file
97
 * @param provider - Provider to add
98
 */
99
function addProviderToAppConfig(
100
  tree: Tree,
101
  filePath: string,
102
  provider: string
103
): void;
104

105
/**
106
 * Add provider to Angular component
107
 * @param tree - Virtual file system tree
108
 * @param componentPath - Path to the component file
109
 * @param provider - Provider to add
110
 */
111
function addProviderToComponent(
112
  tree: Tree,
113
  componentPath: string,
114
  provider: string
115
): void;
116

117
/**
118
 * Add provider to Angular module
119
 * @param tree - Virtual file system tree
120
 * @param modulePath - Path to the module file
121
 * @param provider - Provider to add
122
 */
123
function addProviderToModule(
124
  tree: Tree,
125
  modulePath: string,
126
  provider: string
127
): void;
128

129
/**
130
 * Add view provider to Angular component
131
 * @param tree - Virtual file system tree
132
 * @param componentPath - Path to the component file
133
 * @param provider - View provider to add
134
 */
135
function addViewProviderToComponent(
136
  tree: Tree,
137
  componentPath: string,
138
  provider: string
139
): void;
140
```
141

142
**Usage Example:**
143

144
```typescript
145
import { addProviderToBootstrapApplication } from "@nx/angular/src/utils";
146

147
// Add HttpClient provider to main.ts
148
addProviderToBootstrapApplication(
149
  tree,
150
  "src/main.ts",
151
  "provideHttpClient()"
152
);
153
```
154

155
#### Standalone Detection
156

157
Utility to check if Angular components, directives, or pipes are standalone.
158

159
```typescript { .api }
160
/**
161
 * Check if Component, Directive or Pipe is standalone
162
 * @param tree - Virtual file system tree
163
 * @param sourceFile - TypeScript source file
164
 * @param decoratorName - Name of the decorator to check
165
 * @returns True if the component is standalone
166
 */
167
function isStandalone(
168
  tree: Tree,
169
  sourceFile: ts.SourceFile,
170
  decoratorName: DecoratorName
171
): boolean;
172

173
type DecoratorName = 'Component' | 'Directive' | 'Pipe';
174
```
175

176
### Routing Utilities
177

178
Functions for managing Angular routing configurations.
179

180
```typescript { .api }
181
/**
182
 * Add a new route to a routes definition
183
 * @param tree - Virtual file system tree
184
 * @param routesFile - Path to the routes file
185
 * @param route - Route configuration to add
186
 * @param lazy - Whether the route should be lazy loaded
187
 * @param routesConst - Name of the routes constant
188
 * @param importPath - Import path for the route component
189
 */
190
function addRoute(
191
  tree: Tree,
192
  routesFile: string,
193
  route: string,
194
  lazy?: boolean,
195
  routesConst?: string,
196
  importPath?: string
197
): void;
198

199
/**
200
 * Add provider to route configuration
201
 * @param tree - Virtual file system tree
202
 * @param routesFile - Path to the routes file
203
 * @param provider - Provider to add to route
204
 */
205
function addProviderToRoute(
206
  tree: Tree,
207
  routesFile: string,
208
  provider: string
209
): void;
210
```
211

212
**Usage Example:**
213

214
```typescript
215
import { addRoute } from "@nx/angular/src/utils";
216

217
// Add a lazy-loaded route
218
addRoute(
219
  tree,
220
  "src/app/app.routes.ts",
221
  "{ path: 'feature', loadComponent: () => import('./feature/feature.component').then(m => m.FeatureComponent) }",
222
  true
223
);
224
```
225

226
### Generator Utilities
227

228
Helper functions specifically designed for use within generators.
229

230
#### Module Finding and Manipulation
231

232
```typescript { .api }
233
/**
234
 * Find NgModule file in directory hierarchy
235
 * @param tree - Virtual file system tree
236
 * @param path - Starting path to search from
237
 * @param module - Optional specific module name to find
238
 * @returns Path to the found module or null
239
 */
240
function findModule(
241
  tree: Tree,
242
  path: string,
243
  module?: string
244
): string | null;
245

246
/**
247
 * Add component/directive/pipe to NgModule
248
 * @param tree - Virtual file system tree
249
 * @param path - Path where the item is located
250
 * @param modulePath - Path to the module file
251
 * @param name - Name of the item
252
 * @param className - Class name of the item
253
 * @param fileName - File name of the item
254
 * @param ngModuleProperty - NgModule property to add to
255
 * @param isFlat - Whether the structure is flat
256
 * @param isExported - Whether the item should be exported
257
 */
258
function addToNgModule(
259
  tree: Tree,
260
  path: string,
261
  modulePath: string,
262
  name: string,
263
  className: string,
264
  fileName: string,
265
  ngModuleProperty: ngModuleDecoratorProperty,
266
  isFlat?: boolean,
267
  isExported?: boolean
268
): void;
269

270
/**
271
 * Insert property into NgModule decorator
272
 * @param tree - Virtual file system tree
273
 * @param modulePath - Path to the module file
274
 * @param name - Name of the property to insert
275
 * @param property - NgModule property type
276
 */
277
function insertNgModuleProperty(
278
  tree: Tree,
279
  modulePath: string,
280
  name: string,
281
  property: ngModuleDecoratorProperty
282
): void;
283

284
/**
285
 * Insert import into NgModule
286
 * @param tree - Virtual file system tree
287
 * @param modulePath - Path to the module file
288
 * @param importName - Name of the import to add
289
 */
290
function insertNgModuleImport(
291
  tree: Tree,
292
  modulePath: string,
293
  importName: string
294
): void;
295

296
type ngModuleDecoratorProperty = 
297
  | 'imports'
298
  | 'exports'
299
  | 'declarations'
300
  | 'providers'
301
  | 'bootstrap';
302
```
303

304
**Usage Example:**
305

306
```typescript
307
import { findModule, addToNgModule } from "@nx/angular/src/generators/utils";
308

309
// Find the nearest module and add a component to it
310
const modulePath = findModule(tree, "src/app/feature");
311
if (modulePath) {
312
  addToNgModule(
313
    tree,
314
    "src/app/feature",
315
    modulePath,
316
    "feature-component",
317
    "FeatureComponent",
318
    "feature.component",
319
    "declarations"
320
  );
321
}
322
```
323

324
### Tailwind Utilities
325

326
Utility functions for Tailwind CSS integration.
327

328
```typescript { .api }
329
/**
330
 * Generates glob patterns for Tailwind CSS based on app dependencies
331
 * @param dirPath - Directory path of the application
332
 * @param fileGlobPattern - Optional file glob pattern to use
333
 * @returns Array of glob patterns for Tailwind CSS configuration
334
 */
335
function createGlobPatternsForDependencies(
336
  dirPath: string,
337
  fileGlobPattern?: string
338
): string[];
339
```
340

341
**Usage Example:**
342

343
```typescript
344
import { createGlobPatternsForDependencies } from "@nx/angular/tailwind";
345

346
// Generate patterns for Tailwind CSS configuration
347
const patterns = createGlobPatternsForDependencies(__dirname);
348

349
// Use in tailwind.config.js
350
module.exports = {
351
  content: [
352
    ...patterns,
353
    "./src/**/*.{html,ts}"
354
  ],
355
  // ... rest of config
356
};
357
```
358

359
### Component Testing Utilities
360

361
Utilities for Cypress component testing integration.
362

363
```typescript { .api }
364
/**
365
 * Angular Nx preset for Cypress Component Testing
366
 * @param pathToConfig - Path to the Cypress configuration
367
 * @param options - Optional configuration options
368
 * @returns Cypress configuration object
369
 */
370
function nxComponentTestingPreset(
371
  pathToConfig: string,
372
  options?: NxComponentTestingPresetOptions
373
): CypressConfig;
374

375
interface NxComponentTestingPresetOptions {
376
  buildTarget?: string;
377
  ctViteConfig?: string;
378
}
379

380
interface CypressConfig {
381
  component: {
382
    devServer: {
383
      framework: string;
384
      bundler: string;
385
      options?: any;
386
    };
387
    specPattern: string;
388
    indexHtmlFile?: string;
389
  };
390
}
391
```
392

393
**Usage Example:**
394

395
```typescript
396
import { nxComponentTestingPreset } from "@nx/angular/plugins/component-testing";
397

398
export default nxComponentTestingPreset(__filename, {
399
  buildTarget: "my-app:build"
400
});
401
```
402

403
### Advanced Generator Utilities
404

405
Advanced utility functions available through `@nx/angular/src/generators/utils` for complex Angular module manipulation tasks.
406

407
#### Module Discovery Functions
408

409
Functions for locating and working with Angular modules within the file system.
410

411
```typescript { .api }
412
/**
413
 * Find an Angular module file in the file system tree
414
 * @param tree - Virtual file system tree
415
 * @param path - Starting path to search from
416
 * @param module - Optional specific module file name
417
 * @returns Path to the found module file
418
 */
419
function findModule(tree: Tree, path: string, module?: string): string;
420

421
/**
422
 * Add a component, directive, or pipe to an Angular module
423
 * @param tree - Virtual file system tree
424
 * @param path - Path to the component/directive/pipe file
425
 * @param moduleOptions - Configuration for adding to module
426
 */
427
function addToNgModule(
428
  tree: Tree,
429
  path: string,
430
  moduleOptions: AddToModuleOptions
431
): void;
432

433
interface AddToModuleOptions {
434
  module?: string;
435
  path?: string;
436
  name: string;
437
  flat?: boolean;
438
  export?: boolean;
439
  skipImport?: boolean;
440
}
441
```
442

443
#### NgModule AST Manipulation
444

445
Functions for directly manipulating NgModule decorator properties.
446

447
```typescript { .api }
448
/**
449
 * Insert a property into an NgModule decorator
450
 * @param tree - Virtual file system tree
451
 * @param modulePath - Path to the module file
452
 * @param name - Name of the item to add
453
 * @param property - NgModule property to add to
454
 */
455
function insertNgModuleProperty(
456
  tree: Tree,
457
  modulePath: string,
458
  name: string,
459
  property: NgModuleDecoratorProperty
460
): void;
461

462
/**
463
 * Insert an import into an NgModule decorator
464
 * @param tree - Virtual file system tree
465
 * @param modulePath - Path to the module file
466
 * @param className - Name of the class to import
467
 * @param importPath - Path to import from
468
 */
469
function insertNgModuleImport(
470
  tree: Tree,
471
  modulePath: string,
472
  className: string,
473
  importPath: string
474
): void;
475

476
type NgModuleDecoratorProperty = 'imports' | 'providers' | 'declarations' | 'exports';
477
```
478

479
**Usage Examples:**
480

481
```typescript
482
import { 
483
  findModule, 
484
  addToNgModule, 
485
  insertNgModuleProperty,
486
  insertNgModuleImport
487
} from "@nx/angular/src/generators/utils";
488

489
// Find the nearest module file
490
const modulePath = findModule(tree, "src/app/feature", "feature.module.ts");
491

492
// Add a component to a module with export
493
addToNgModule(tree, "src/app/feature/my-component.ts", {
494
  module: modulePath,
495
  name: "MyComponent",
496
  export: true
497
});
498

499
// Add a service to module providers
500
insertNgModuleProperty(tree, modulePath, "MyService", "providers");
501

502
// Add an import to the module
503
insertNgModuleImport(tree, modulePath, "CommonModule", "@angular/common");
504
```
505

506
## Types
507

508
```typescript { .api }
509
import * as ts from 'typescript';
510

511
interface Tree {
512
  read(filePath: string): Buffer | null;
513
  write(filePath: string, content: Buffer | string): void;
514
  exists(filePath: string): boolean;
515
  delete(filePath: string): void;
516
  rename(from: string, to: string): void;
517
  children(dirPath: string): string[];
518
  isFile(filePath: string): boolean;
519
}
520

521
type DecoratorName = 'Component' | 'Directive' | 'Pipe';
522

523
type ngModuleDecoratorProperty = 
524
  | 'imports'
525
  | 'exports'
526
  | 'declarations'
527
  | 'providers'
528
  | 'bootstrap';
529

530
interface NxComponentTestingPresetOptions {
531
  buildTarget?: string;
532
  ctViteConfig?: string;
533
}
534
```