@nx/angular 23.0.0-beta.21 → 23.0.0-beta.23

package/src/migrations/update-21-3-0/update-angular-cli.md

@@ -0,0 +1,23 @@
+#### Sample Code Changes
+
+Update the `@angular/cli` package version in the `package.json` file at the workspace root to **~20.1.0**.
+
+##### Before
+
+```json title="package.json"
+{
+  "devDependencies": {
+    "@angular/cli": "~20.0.0"
+  }
+}
+```
+
+##### After
+
+```json title="package.json" {3}
+{
+  "devDependencies": {
+    "@angular/cli": "~20.1.0"
+  }
+}
+```

package/src/migrations/update-21-5-0/remove-default-karma-configuration-files.md

@@ -0,0 +1,122 @@
+#### Remove the Default Karma Configuration Files
+
+Removes Karma configuration files that match the default configuration generated by Angular CLI to reduce boilerplate code in the workspace. The migration also removes the `karmaConfig` option from project targets when the configuration file is removed.
+
+#### Examples
+
+The migration will remove `karma.conf.js` files that contain only default settings and update the project configuration:
+
+##### Before
+
+```javascript title="apps/my-app/karma.conf.js"
+// Karma configuration file, see link for more information
+// https://karma-runner.github.io/1.0/config/configuration-file.html
+
+module.exports = function (config) {
+  config.set({
+    basePath: '',
+    frameworks: ['jasmine', '@angular-devkit/build-angular'],
+    plugins: [
+      require('karma-jasmine'),
+      require('karma-chrome-launcher'),
+      require('karma-jasmine-html-reporter'),
+      require('karma-coverage'),
+      require('@angular-devkit/build-angular/plugins/karma'),
+    ],
+    client: {
+      jasmine: {
+        // you can add configuration options for Jasmine here
+        // the possible options are listed at https://jasmine.github.io/api/edge/Configuration.html
+        // for example, you can disable the random execution with `random: false`
+        // or set a specific seed with `seed: 4321`
+      },
+    },
+    jasmineHtmlReporter: {
+      suppressAll: true, // removes the duplicated traces
+    },
+    coverageReporter: {
+      dir: require('path').join(__dirname, '../../coverage/my-app'),
+      subdir: '.',
+      reporters: [{ type: 'html' }, { type: 'text-summary' }],
+    },
+    reporters: ['progress', 'kjhtml'],
+    browsers: ['Chrome'],
+    restartOnFileChange: true,
+  });
+};
+```
+
+```json title="apps/my-app/project.json" {7}
+{
+  "name": "my-app",
+  "targets": {
+    "test": {
+      "executor": "@angular-devkit/build-angular:karma",
+      "options": {
+        "karmaConfig": "apps/my-app/karma.conf.js",
+        "polyfills": ["zone.js", "zone.js/testing"]
+      }
+    }
+  }
+}
+```
+
+##### After
+
+File `apps/my-app/karma.conf.js` is removed.
+
+```json title="apps/my-app/project.json"
+{
+  "name": "my-app",
+  "targets": {
+    "test": {
+      "executor": "@angular-devkit/build-angular:karma",
+      "options": {
+        "polyfills": ["zone.js", "zone.js/testing"]
+      }
+    }
+  }
+}
+```
+
+If the Karma configuration contains customizations, the migration will preserve the file and configuration:
+
+##### Before
+
+```javascript title="apps/custom-app/karma.conf.js"
+module.exports = function (config) {
+  config.set({
+    basePath: '',
+    frameworks: ['jasmine', '@angular-devkit/build-angular'],
+    plugins: [
+      require('karma-jasmine'),
+      require('karma-chrome-launcher'),
+      require('karma-jasmine-html-reporter'),
+      require('karma-coverage'),
+      require('@angular-devkit/build-angular/plugins/karma'),
+    ],
+    browsers: ['ChromeHeadless'], // Custom browser configuration
+    restartOnFileChange: true,
+  });
+};
+```
+
+##### After
+
+```javascript title="apps/custom-app/karma.conf.js"
+module.exports = function (config) {
+  config.set({
+    basePath: '',
+    frameworks: ['jasmine', '@angular-devkit/build-angular'],
+    plugins: [
+      require('karma-jasmine'),
+      require('karma-chrome-launcher'),
+      require('karma-jasmine-html-reporter'),
+      require('karma-coverage'),
+      require('@angular-devkit/build-angular/plugins/karma'),
+    ],
+    browsers: ['ChromeHeadless'], // Custom browser configuration
+    restartOnFileChange: true,
+  });
+};
+```

package/src/migrations/update-21-5-0/set-tsconfig-option.md

@@ -0,0 +1,114 @@
+#### Set `tsConfig` option for build and test targets
+
+- Set the `tsConfig` option in the target options for library build executors. It moves the value from the target `development` configuration and it doesn't set it if the option is already set.
+- Set `tsconfig.spec.json` as the `tsConfig` option in the target options for the `@nx/jest:jest` executor. It only does it if the file exists and the options is not already set.
+
+#### Examples
+
+The migration will move the `tsConfig` option for library build executors (`@nx/angular:ng-packagr-lite` and `@nx/angular:package`) from the `development` configuration to the target options if it's not already set:
+
+##### Before
+
+```json title="libs/lib1/project.json" {7}
+{
+  "targets": {
+    "build": {
+      "executor": "@nx/angular:ng-packagr-lite",
+      "configurations": {
+        "development": {
+          "tsConfig": "libs/lib1/tsconfig.lib.dev.json"
+        }
+      }
+    }
+  }
+}
+```
+
+##### After
+
+```json title="libs/lib1/project.json" {6,9}
+{
+  "targets": {
+    "build": {
+      "executor": "@nx/angular:ng-packagr-lite",
+      "options": {
+        "tsConfig": "libs/lib1/tsconfig.lib.dev.json"
+      },
+      "configurations": {
+        "development": {}
+      }
+    }
+  }
+}
+```
+
+The migration will set the `tsConfig` option for the `@nx/jest:jest` executor when the `tsconfig.spec.json` file exists and the option is not already set:
+
+##### Before
+
+```json title="apps/app1/project.json"
+{
+  "targets": {
+    "test": {
+      "executor": "@nx/jest:jest"
+    }
+  }
+}
+```
+
+##### After
+
+```json title="apps/app1/project.json" {6}
+{
+  "targets": {
+    "test": {
+      "executor": "@nx/jest:jest",
+      "options": {
+        "tsConfig": "apps/app1/tsconfig.spec.json"
+      }
+    }
+  }
+}
+```
+
+If the `tsConfig` option is already set in the target options, the migration will not modify the configuration:
+
+##### Before
+
+```json title="libs/lib1/project.json" {6,10}
+{
+  "targets": {
+    "build": {
+      "executor": "@nx/angular:ng-packagr-lite",
+      "options": {
+        "tsConfig": "libs/lib1/tsconfig.lib.json"
+      },
+      "configurations": {
+        "development": {
+          "tsConfig": "libs/lib1/tsconfig.lib.dev.json"
+        }
+      }
+    }
+  }
+}
+```
+
+##### After
+
+```json title="libs/lib1/project.json" {6,10}
+{
+  "targets": {
+    "build": {
+      "executor": "@nx/angular:ng-packagr-lite",
+      "options": {
+        "tsConfig": "libs/lib1/tsconfig.lib.json"
+      },
+      "configurations": {
+        "development": {
+          "tsConfig": "libs/lib1/tsconfig.lib.dev.json"
+        }
+      }
+    }
+  }
+}
+```

package/src/migrations/update-21-5-0/update-angular-cli.md

@@ -0,0 +1,23 @@
+#### Sample Code Changes
+
+Update the `@angular/cli` package version in the `package.json` file at the workspace root to **~20.2.0**.
+
+##### Before
+
+```json title="package.json"
+{
+  "devDependencies": {
+    "@angular/cli": "~20.1.0"
+  }
+}
+```
+
+##### After
+
+```json title="package.json" {3}
+{
+  "devDependencies": {
+    "@angular/cli": "~20.2.0"
+  }
+}
+```

package/src/migrations/update-21-6-1/update-angular-cli.md

@@ -0,0 +1,23 @@
+#### Sample Code Changes
+
+Update the `@angular/cli` package version in the `package.json` file at the workspace root to **~20.3.0**.
+
+##### Before
+
+```json title="package.json"
+{
+  "devDependencies": {
+    "@angular/cli": "~20.2.0"
+  }
+}
+```
+
+##### After
+
+```json title="package.json" {3}
+{
+  "devDependencies": {
+    "@angular/cli": "~20.3.0"
+  }
+}
+```

package/src/migrations/update-22-3-0/set-isolated-modules.md

@@ -0,0 +1,76 @@
+#### Set `isolatedModules` to `true` in TypeScript test configurations
+
+Sets the TypeScript `isolatedModules` compiler option to `true` in `tsconfig.spec.json` files for Angular projects using the Jest test runner.
+
+#### Examples
+
+The migration updates TypeScript test configuration files in Angular projects using the Jest test runner to set the `isolatedModules` compiler option:
+
+##### Before
+
+```jsonc {3-5}
+// apps/my-app/tsconfig.spec.json
+{
+  "compilerOptions": {
+    "outDir": "./out-tsc/spec",
+  },
+}
+```
+
+##### After
+
+```jsonc {4-5}
+// apps/my-app/tsconfig.spec.json
+{
+  "compilerOptions": {
+    "outDir": "./out-tsc/spec",
+    "isolatedModules": true,
+  },
+}
+```
+
+If the value is already set to `true` or inherited from an extended tsconfig file, the migration will not modify the configuration:
+
+##### Before
+
+```jsonc {4}
+// tsconfig.json
+{
+  "compilerOptions": {
+    "isolatedModules": true,
+  },
+}
+```
+
+```jsonc {4-6}
+// apps/my-app/tsconfig.spec.json
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/spec",
+  },
+}
+```
+
+##### After
+
+```jsonc {4}
+// tsconfig.json
+{
+  "compilerOptions": {
+    "isolatedModules": true,
+  },
+}
+```
+
+```jsonc {4-6}
+// apps/my-app/tsconfig.spec.json
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/spec",
+  },
+}
+```
+
+The migration only processes TypeScript test configuration files (`tsconfig.spec.json` or custom test tsconfig files referenced by `@nx/jest:jest` tasks) in Angular projects.

package/src/migrations/update-22-3-0/update-jest-preset-angular-setup.md

@@ -0,0 +1,21 @@
+#### Update Jest Preset Angular Setup
+
+Replaces the removed `jest-preset-angular/setup-jest` import with the new `setupZoneTestEnv` function from `jest-preset-angular/setup-env/zone`.
+
+Starting with `jest-preset-angular` v15, the `setup-jest` files have been removed and replaced with explicit setup functions. The old `setup-jest` import only supported zone-based testing (zoneless support was added in v14.3.0 with the new `setupZonelessTestEnv` function), so all projects using the removed import are migrated to use `setupZoneTestEnv`.
+
+#### Examples
+
+##### Before
+
+```ts title="apps/my-app/src/test-setup.ts"
+import 'jest-preset-angular/setup-jest';
+```
+
+##### After
+
+```ts title="apps/my-app/src/test-setup.ts"
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
+
+setupZoneTestEnv();
+```

package/src/migrations/update-22-3-0/update-module-resolution.md

@@ -0,0 +1,81 @@
+#### Update `module` to `preserve` and `moduleResolution` to `bundler` in TypeScript configurations
+
+Updates the TypeScript `module` and `moduleResolution` compiler options to `'preserve'` and `'bundler'` respectively for Angular projects. These settings are required for Angular's build system to work correctly with modern module resolution algorithms used by bundlers like Webpack, Vite, and esbuild.
+
+#### Examples
+
+The migration updates TypeScript configuration files in Angular projects to set both compiler options:
+
+##### Before
+
+```jsonc {4-5}
+// apps/my-app/tsconfig.app.json
+{
+  "compilerOptions": {
+    "module": "es2020",
+    "moduleResolution": "node",
+  },
+}
+```
+
+##### After
+
+```jsonc {4-5}
+// apps/my-app/tsconfig.app.json
+{
+  "compilerOptions": {
+    "module": "preserve",
+    "moduleResolution": "bundler",
+  },
+}
+```
+
+If both values are already set correctly and inherited from an extended tsconfig file, the migration will not modify the configuration:
+
+##### Before
+
+```jsonc {5-6}
+// apps/my-app/tsconfig.json
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "preserve",
+    "moduleResolution": "bundler",
+  },
+}
+```
+
+```jsonc {4-6}
+// apps/my-app/tsconfig.app.json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": [],
+  },
+}
+```
+
+##### After
+
+```jsonc {5-6}
+// apps/my-app/tsconfig.json
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "preserve",
+    "moduleResolution": "bundler",
+  },
+}
+```
+
+```jsonc {4-6}
+// apps/my-app/tsconfig.app.json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": [],
+  },
+}
+```
+
+The migration only processes TypeScript configuration files that are referenced by Angular project build targets, ensuring that only Angular-specific configurations are updated.

package/src/migrations/update-22-3-0/update-ssr-webpack-config.md

@@ -0,0 +1,71 @@
+#### Updates Webpack-Based SSR Configuration
+
+Updates the TypeScript configuration and import syntax for webpack-based server-side rendering (SSR) projects. This migration sets `module: "preserve"` and `moduleResolution: "bundler"` in `tsconfig.server.json` to align with Angular's build requirements, and updates server file imports from namespace imports (`import * as express`) to default imports (`import express`) to work correctly with the new module format.
+
+#### Examples
+
+For webpack-based SSR projects (using `@nx/angular:webpack-server` or `@angular-devkit/build-angular:server`), the migration updates the `tsconfig.server.json` file:
+
+##### Before
+
+```jsonc {7-8}
+// apps/my-app/tsconfig.server.json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "target": "es2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "types": ["node"],
+  },
+  "files": ["src/main.server.ts", "src/server.ts"],
+}
+```
+
+##### After
+
+```jsonc {7-8}
+// apps/my-app/tsconfig.server.json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "target": "es2022",
+    "module": "preserve",
+    "moduleResolution": "bundler",
+    "types": ["node"],
+  },
+  "files": ["src/main.server.ts", "src/server.ts"],
+}
+```
+
+The migration also updates import statements in the `server.ts` file to use default imports instead of namespace imports:
+
+##### Before
+
+```ts {2-4}
+// apps/my-app/src/server.ts
+import * as express from 'express';
+import * as compression from 'compression';
+import * as cors from 'cors';
+
+const app = express();
+app.use(compression());
+app.use(cors());
+```
+
+##### After
+
+```ts {2-4}
+// apps/my-app/src/server.ts
+import express from 'express';
+import compression from 'compression';
+import cors from 'cors';
+
+const app = express();
+app.use(compression());
+app.use(cors());
+```
+
+Projects that already have the correct TypeScript configuration or projects without a `tsconfig.server.json` file are not modified by this migration.

package/src/migrations/update-22-3-0/update-typescript-lib.md

@@ -0,0 +1,103 @@
+#### Update TypeScript `lib` compiler option to ES2022
+
+Updates the TypeScript `lib` compiler option in Angular projects to ensure compatibility with Angular v21+, which requires ES2022 as the minimum ECMAScript version. The migration upgrades any ES versions older than ES2022 (such as ES2015, ES2020, etc.) to ES2022 while preserving other library entries like `'dom'`, `'webworker'`, etc.
+
+#### Examples
+
+The migration processes TypeScript configuration files referenced by Angular project build targets and updates the `lib` compiler option when outdated ES versions are detected:
+
+##### Before
+
+```jsonc {4}
+// apps/my-app/tsconfig.app.json
+{
+  "compilerOptions": {
+    "lib": ["es2020", "dom"],
+  },
+}
+```
+
+##### After
+
+```jsonc {4}
+// apps/my-app/tsconfig.app.json
+{
+  "compilerOptions": {
+    "lib": ["dom", "es2022"],
+  },
+}
+```
+
+When the `lib` array contains only an ES version older than ES2022 without additional entries, it is upgraded:
+
+##### Before
+
+```jsonc {4}
+// apps/my-app/tsconfig.app.json
+{
+  "compilerOptions": {
+    "lib": ["es2020"],
+  },
+}
+```
+
+##### After
+
+```jsonc {4}
+// apps/my-app/tsconfig.app.json
+{
+  "compilerOptions": {
+    "lib": ["es2022"],
+  },
+}
+```
+
+If the configuration already uses ES2022 or higher (e.g., `'es2023'`, `'esnext'`), no changes are made:
+
+##### Before
+
+```jsonc {4}
+// apps/my-app/tsconfig.app.json
+{
+  "compilerOptions": {
+    "lib": ["es2022", "dom"],
+  },
+}
+```
+
+##### After
+
+```jsonc {4}
+// apps/my-app/tsconfig.app.json
+{
+  "compilerOptions": {
+    "lib": ["es2022", "dom"],
+  },
+}
+```
+
+When the `lib` array contains multiple library entries, only the ES version is upgraded while all other entries are preserved:
+
+##### Before
+
+```jsonc {4}
+// apps/my-app/tsconfig.app.json
+{
+  "compilerOptions": {
+    "lib": ["es2020", "dom", "webworker"],
+  },
+}
+```
+
+##### After
+
+```jsonc {4}
+// apps/my-app/tsconfig.app.json
+{
+  "compilerOptions": {
+    "lib": ["dom", "webworker", "es2022"],
+  },
+}
+```
+
+The migration only processes TypeScript configuration files that are referenced by Angular project build targets, ensuring that only Angular-specific configurations are updated.

package/src/migrations/update-22-3-0/update-unit-test-runner-option.md

@@ -0,0 +1,33 @@
+#### Update `vitest` unit test runner option to `vitest-analog` in generator defaults
+
+Updates the `unitTestRunner` generator default from `vitest` to `vitest-analog` in `nx.json`. The `vitest` option has been split into two explicit options: `vitest-angular` (uses `@angular/build:unit-test`) and `vitest-analog` (uses AnalogJS-based setup).
+
+#### Examples
+
+The migration updates generator defaults in `nx.json`:
+
+##### Before
+
+```jsonc {5}
+// nx.json
+{
+  "generators": {
+    "@nx/angular:application": {
+      "unitTestRunner": "vitest",
+    },
+  },
+}
+```
+
+##### After
+
+```jsonc {5}
+// nx.json
+{
+  "generators": {
+    "@nx/angular:application": {
+      "unitTestRunner": "vitest-analog",
+    },
+  },
+}
+```