0
# Migrations
1

2
Migration system in @nx/angular provides automated code transformations for updating Angular versions, ESLint configurations, build tool integrations, and other package dependencies across workspace projects.
3

4
## Capabilities
5

6
### Angular CLI Version Updates
7

8
Automated migrations for updating Angular CLI versions across major and minor releases.
9

10
```typescript { .api }
11
interface MigrationOptions {
12
  packageName: string;
13
  version: string;
14
  from: string;
15
  to: string;
16
}
17

18
interface AngularCliMigration extends MigrationOptions {
19
  packageName: '@angular/cli';
20
  targetVersion: string;
21
  skipFormat?: boolean;
22
}
23
```
24

25
**Available Angular CLI Migrations:**
26

27
- `update-angular-cli-version-16-1-0` - Updates to Angular CLI 16.1.0
28
- `update-angular-cli-version-16-2-0` - Updates to Angular CLI 16.2.0
29
- `update-angular-cli-version-17-0-0` - Updates to Angular CLI 17.0.0
30
- `update-angular-cli-version-17-1-0` - Updates to Angular CLI 17.1.0
31
- `update-angular-cli-version-17-2-0` - Updates to Angular CLI 17.2.0
32
- `update-angular-cli-version-17-3-0` - Updates to Angular CLI 17.3.0
33
- `update-angular-cli-version-18-0-0` - Updates to Angular CLI 18.0.0
34
- `update-angular-cli-version-18-1-0` - Updates to Angular CLI 18.1.0
35
- `update-angular-cli-version-18-2-0` - Updates to Angular CLI 18.2.0
36
- `update-angular-cli-version-19-0-0` - Updates to Angular CLI 19.0.0
37
- `update-angular-cli-version-19-1-0` - Updates to Angular CLI 19.1.0
38
- `update-angular-cli-version-19-2-0` - Updates to Angular CLI 19.2.0
39
- `update-angular-cli-version-19-3-0` - Updates to Angular CLI 19.3.0
40
- `update-angular-cli-version-20-0-0` - Updates to Angular CLI 20.0.0
41
- `update-angular-cli-version-21-0-0` - Updates to Angular CLI 21.0.0
42

43
### ESLint and Angular ESLint Updates
44

45
Migrations for updating ESLint rules and Angular ESLint configurations.
46

47
```typescript { .api }
48
interface ESLintMigrationOptions {
49
  skipFormat?: boolean;
50
  skipPackageJson?: boolean;
51
}
52
```
53

54
**ESLint Migration Examples:**
55

56
#### Rename Angular ESLint Accessibility Rules
57

58
```typescript { .api }
59
/**
60
 * Removes 'accessibility-' prefix from Angular ESLint rules
61
 * Migrates rules like @angular-eslint/accessibility-click-events-have-key-events
62
 * to @angular-eslint/click-events-have-key-events
63
 */
64
interface RenameAccessibilityRulesMigration {
65
  name: 'rename-angular-eslint-accesibility-rules';
66
  description: 'Remove accessibility- prefix from Angular ESLint rules';
67
}
68
```
69

70
#### Add TypeScript ESLint Utils
71

72
```typescript { .api }
73
/**
74
 * Installs @typescript-eslint/utils package for Angular ESLint v18+
75
 */
76
interface AddTypeScriptESLintUtilsMigration {
77
  name: 'add-typescript-eslint-utils';
78
  description: 'Install @typescript-eslint/utils package for Angular ESLint v18+';
79
}
80
```
81

82
#### Disable Angular ESLint Prefer Standalone
83

84
```typescript { .api }
85
/**
86
 * Disables prefer-standalone rule for Angular 19+
87
 */
88
interface DisablePreferStandaloneMigration {
89
  name: 'disable-angular-eslint-prefer-standalone';
90
  description: 'Disable prefer-standalone rule for Angular 19+';
91
}
92
```
93

94
### Module Federation Updates
95

96
Migrations for updating Module Federation configurations and imports.
97

98
```typescript { .api }
99
interface ModuleFederationMigrationOptions {
100
  skipFormat?: boolean;
101
}
102
```
103

104
**Module Federation Migration Examples:**
105

106
#### Update Module Federation Config Import
107

108
```typescript { .api }
109
/**
110
 * Updates ModuleFederationConfig import to use @nx/module-federation
111
 * Changes: import { ModuleFederationConfig } from '@nx/webpack'
112
 * To: import { ModuleFederationConfig } from '@nx/module-federation'
113
 */
114
interface UpdateMFConfigImportMigration {
115
  name: 'update-20-2-0-update-module-federation-config-import';
116
  description: 'Update ModuleFederationConfig import to use @nx/module-federation';
117
}
118
```
119

120
#### Update withModuleFederation Import
121

122
```typescript { .api }
123
/**
124
 * Updates withModuleFederation import to use @nx/module-federation/angular
125
 * Changes: import { withModuleFederation } from '@nx/angular/mf'
126
 * To: import { withModuleFederation } from '@nx/module-federation/angular'
127
 */
128
interface UpdateWithMFImportMigration {
129
  name: 'update-20-2-0-update-with-module-federation-import';
130
  description: 'Update withModuleFederation import to use @nx/module-federation/angular';
131
}
132
```
133

134
#### Add Module Federation Environment Variable
135

136
```typescript { .api }
137
/**
138
 * Adds NX_MF_DEV_SERVER_STATIC_REMOTES to target defaults
139
 */
140
interface AddMFEnvVarMigration {
141
  name: 'add-module-federation-env-var-to-target-defaults';
142
  description: 'Add NX_MF_DEV_SERVER_STATIC_REMOTES to target defaults';
143
}
144
```
145

146
### Build and Development Server Updates
147

148
Migrations for updating build configurations and development servers.
149

150
```typescript { .api }
151
interface BuildServerMigrationOptions {
152
  skipFormat?: boolean;
153
  targetDefaults?: boolean;
154
}
155
```
156

157
**Build Server Migration Examples:**
158

159
#### Rename Webpack Dev Server Executor
160

161
```typescript { .api }
162
/**
163
 * Renames @nx/angular:webpack-dev-server to @nx/angular:dev-server
164
 */
165
interface RenameWebpackDevServerMigration {
166
  name: 'rename-webpack-dev-server-executor';
167
  description: 'Rename @nx/angular:webpack-dev-server to @nx/angular:dev-server';
168
}
169
```
170

171
#### Replace Angular Universal Builders
172

173
```typescript { .api }
174
/**
175
 * Replaces @nguniversal/builders with @angular-devkit/build-angular
176
 */
177
interface ReplaceNguniversalBuildersMigration {
178
  name: 'replace-nguniversal-builders';
179
  description: 'Replace @nguniversal/builders with @angular-devkit/build-angular';
180
}
181
```
182

183
#### Replace Angular Universal Engines
184

185
```typescript { .api }
186
/**
187
 * Replaces @nguniversal/ packages with @angular/ssr
188
 */
189
interface ReplaceNguniversalEnginesMigration {
190
  name: 'replace-nguniversal-engines';
191
  description: 'Replace @nguniversal/ packages with @angular/ssr';
192
}
193
```
194

195
### Dependency and Configuration Updates
196

197
Migrations for managing project dependencies and build configurations.
198

199
```typescript { .api }
200
interface DependencyMigrationOptions {
201
  skipFormat?: boolean;
202
  skipPackageJson?: boolean;
203
}
204
```
205

206
**Dependency Migration Examples:**
207

208
#### Add Browser Sync Dependency
209

210
```typescript { .api }
211
/**
212
 * Adds browser-sync dev dependency for SSR dev server usage
213
 */
214
interface AddBrowserSyncDependencyMigration {
215
  name: 'add-browser-sync-dependency';
216
  description: 'Add browser-sync dev dependency for SSR dev server usage';
217
}
218
```
219

220
#### Add Autoprefixer Dependency
221

222
```typescript { .api }
223
/**
224
 * Adds autoprefixer dev dependency for ng-packagr executors
225
 */
226
interface AddAutoprefixerDependencyMigration {
227
  name: 'add-autoprefixer-dependency';
228
  description: 'Add autoprefixer dev dependency for ng-packagr executors';
229
}
230
```
231

232
#### Set Update Buildable Deps
233

234
```typescript { .api }
235
/**
236
 * Sets updateBuildableProjectDepsInPackageJson to true for buildable projects
237
 */
238
interface SetUpdateBuildableDependenciesMigration {
239
  name: 'explicitly-set-projects-to-update-buildable-deps';
240
  description: 'Set updateBuildableProjectDepsInPackageJson to true';
241
}
242
```
243

244
#### Update Zone.js Deep Import
245

246
```typescript { .api }
247
/**
248
 * Replaces deep imports from zone.js with standard imports
249
 * Changes: import 'zone.js/dist/zone'
250
 * To: import 'zone.js'
251
 */
252
interface UpdateZoneJsImportMigration {
253
  name: 'update-zone-js-deep-import';
254
  description: 'Replace deep imports from zone.js with standard imports';
255
}
256
```
257

258
### Migration Execution
259

260
Migrations are automatically executed when running `nx migrate` or when updating the @nx/angular package. They can also be run individually:
261

262
```bash
263
# Run all pending migrations
264
nx migrate --run-migrations
265

266
# Run a specific migration
267
nx migrate --run-migrations=migrations.json --only=update-angular-cli-version-19-0-0
268
```
269

270
### Custom Migration Creation
271

272
For creating custom migrations, the migration system follows a specific pattern:
273

274
```typescript { .api }
275
/**
276
 * Migration function interface
277
 * @param tree - Virtual file system tree
278
 * @param options - Migration-specific options
279
 * @returns Promise resolving to callback function or void
280
 */
281
interface MigrationFunction {
282
  (tree: Tree, options: any): Promise<GeneratorCallback | void> | GeneratorCallback | void;
283
}
284

285
interface MigrationDefinition {
286
  version: string;
287
  description?: string;
288
  implementation: string;
289
  factory?: string;
290
  schematic?: any;
291
}
292

293
interface MigrationsJson {
294
  generators?: Record<string, MigrationDefinition>;
295
  packageJsonUpdates?: Record<string, {
296
    version: string;
297
    packages?: Record<string, {
298
      version: string;
299
      ifPackageInstalled?: string;
300
    }>;
301
  }>;
302
}
303
```
304

305
**Example Migration Implementation:**
306

307
```typescript
308
import { Tree, formatFiles } from '@nx/devkit';
309

310
export default async function updateSomething(tree: Tree) {
311
  // Find all Angular projects
312
  const projects = getProjects(tree);
313
  
314
  for (const [projectName, project] of projects) {
315
    if (project.projectType === 'application') {
316
      // Update project configuration
317
      updateProjectConfiguration(tree, projectName, {
318
        ...project,
319
        targets: {
320
          ...project.targets,
321
          build: {
322
            ...project.targets.build,
323
            executor: '@nx/angular:application'
324
          }
325
        }
326
      });
327
    }
328
  }
329
  
330
  await formatFiles(tree);
331
}
332
```
333

334
## Types
335

336
```typescript { .api }
337
interface Tree {
338
  read(filePath: string): Buffer | null;
339
  write(filePath: string, content: Buffer | string): void;
340
  exists(filePath: string): boolean;
341
  delete(filePath: string): void;
342
  rename(from: string, to: string): void;
343
  children(dirPath: string): string[];
344
  isFile(filePath: string): boolean;
345
}
346

347
interface GeneratorCallback {
348
  (): void | Promise<void>;
349
}
350

351
interface MigrationOptions {
352
  packageName: string;
353
  version: string;
354
  from: string;
355
  to: string;
356
  skipFormat?: boolean;
357
  skipPackageJson?: boolean;
358
}
359

360
interface MigrationFunction {
361
  (tree: Tree, options: any): Promise<GeneratorCallback | void> | GeneratorCallback | void;
362
}
363

364
interface MigrationDefinition {
365
  version: string;
366
  description?: string;
367
  implementation: string;
368
  factory?: string;
369
  schematic?: any;
370
}
371
```