@nx/angular 23.0.0-pr.35465.2bc2643 → 23.0.0-rc.0

package/dist/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/dist/src/migrations/update-21-5-0/update-angular-cli.d.ts

@@ -0,0 +1,3 @@
+import { Tree } from '@nx/devkit';
+export declare const angularCliVersion = "~20.2.0";
+export default function (tree: Tree): Promise<void>;

package/dist/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/dist/src/migrations/update-21-5-0/utils/karma-config-analyzer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+export interface RequireInfo {
+    module: string;
+    export?: string;
+    isCall?: boolean;
+    arguments?: KarmaConfigValue[];
+}
+export type KarmaConfigValue = string | boolean | number | KarmaConfigValue[] | {
+    [key: string]: KarmaConfigValue;
+} | RequireInfo | undefined;
+export interface KarmaConfigAnalysis {
+    settings: Map<string, KarmaConfigValue>;
+    hasUnsupportedValues: boolean;
+}
+/**
+ * Analyzes the content of a Karma configuration file to extract its settings.
+ *
+ * @param content The string content of the `karma.conf.js` file.
+ * @returns An object containing the configuration settings and a flag indicating if unsupported values were found.
+ */
+export declare function analyzeKarmaConfig(content: string): KarmaConfigAnalysis;

package/dist/src/migrations/update-21-5-0/utils/karma-config-analyzer.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeKarmaConfig = analyzeKarmaConfig;
+/**
+ * Adapts the private utility from Angular CLI to be used in the migration.
+ */
+const internal_1 = require("@nx/js/internal");
+let ts;
+/**
+ * Analyzes the content of a Karma configuration file to extract its settings.
+ *
+ * @param content The string content of the `karma.conf.js` file.
+ * @returns An object containing the configuration settings and a flag indicating if unsupported values were found.
+ */
+function analyzeKarmaConfig(content) {
+    if (!ts) {
+        ts = (0, internal_1.ensureTypescript)();
+    }
+    const sourceFile = ts.createSourceFile('karma.conf.js', content, ts.ScriptTarget.Latest, true);
+    const settings = new Map();
+    let hasUnsupportedValues = false;
+    function visit(node) {
+        // The Karma configuration is defined within a `config.set({ ... })` call.
+        if (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression) &&
+            node.expression.expression.getText(sourceFile) === 'config' &&
+            node.expression.name.text === 'set' &&
+            node.arguments.length === 1 &&
+            ts.isObjectLiteralExpression(node.arguments[0])) {
+            // We found `config.set`, now we extract the properties from the object literal.
+            for (const prop of node.arguments[0].properties) {
+                if (isSupportedPropertyAssignment(prop)) {
+                    const key = prop.name.text;
+                    const value = extractValue(prop.initializer);
+                    settings.set(key, value);
+                }
+                else {
+                    hasUnsupportedValues = true;
+                }
+            }
+        }
+        else {
+            ts.forEachChild(node, visit);
+        }
+    }
+    function extractValue(node) {
+        switch (node.kind) {
+            case ts.SyntaxKind.StringLiteral:
+                return node.text;
+            case ts.SyntaxKind.NumericLiteral:
+                return Number(node.text);
+            case ts.SyntaxKind.TrueKeyword:
+                return true;
+            case ts.SyntaxKind.FalseKeyword:
+                return false;
+            case ts.SyntaxKind.Identifier: {
+                const identifier = node.text;
+                if (identifier === '__dirname' || identifier === '__filename') {
+                    return identifier;
+                }
+                break;
+            }
+            case ts.SyntaxKind.CallExpression: {
+                const callExpr = node;
+                // Handle require('...')
+                if (ts.isIdentifier(callExpr.expression) &&
+                    callExpr.expression.text === 'require' &&
+                    callExpr.arguments.length === 1 &&
+                    ts.isStringLiteral(callExpr.arguments[0])) {
+                    return { module: callExpr.arguments[0].text };
+                }
+                // Handle calls on a require, e.g. require('path').join()
+                const calleeValue = extractValue(callExpr.expression);
+                if (isRequireInfo(calleeValue)) {
+                    return {
+                        ...calleeValue,
+                        isCall: true,
+                        arguments: callExpr.arguments.map(extractValue),
+                    };
+                }
+                break;
+            }
+            case ts.SyntaxKind.PropertyAccessExpression: {
+                const propAccessExpr = node;
+                // Handle config constants like `config.LOG_INFO`
+                if (ts.isIdentifier(propAccessExpr.expression) &&
+                    propAccessExpr.expression.text === 'config') {
+                    return `config.${propAccessExpr.name.text}`;
+                }
+                const value = extractValue(propAccessExpr.expression);
+                if (isRequireInfo(value)) {
+                    const currentExport = value.export
+                        ? `${value.export}.${propAccessExpr.name.text}`
+                        : propAccessExpr.name.text;
+                    return { ...value, export: currentExport };
+                }
+                break;
+            }
+            case ts.SyntaxKind.ArrayLiteralExpression:
+                return node.elements.map(extractValue);
+            case ts.SyntaxKind.ObjectLiteralExpression: {
+                const obj = {};
+                for (const prop of node.properties) {
+                    if (isSupportedPropertyAssignment(prop)) {
+                        // Recursively extract values for nested objects.
+                        obj[prop.name.text] = extractValue(prop.initializer);
+                    }
+                    else {
+                        hasUnsupportedValues = true;
+                    }
+                }
+                return obj;
+            }
+        }
+        // For complex expressions (like variables) that we don't need to resolve,
+        // we mark the analysis as potentially incomplete.
+        hasUnsupportedValues = true;
+        return undefined;
+    }
+    visit(sourceFile);
+    return { settings, hasUnsupportedValues };
+}
+function isRequireInfo(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        'module' in value);
+}
+function isSupportedPropertyAssignment(prop) {
+    return (ts.isPropertyAssignment(prop) &&
+        (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)));
+}

package/dist/src/migrations/update-21-5-0/utils/karma-config-comparer.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+import { type KarmaConfigAnalysis, type KarmaConfigValue } from './karma-config-analyzer';
+/**
+ * Represents the difference between two Karma configurations.
+ */
+export interface KarmaConfigDiff {
+    /** A map of settings that were added in the project's configuration. */
+    added: Map<string, KarmaConfigValue>;
+    /** A map of settings that were removed from the project's configuration. */
+    removed: Map<string, KarmaConfigValue>;
+    /** A map of settings that were modified between the two configurations. */
+    modified: Map<string, {
+        projectValue: KarmaConfigValue;
+        defaultValue: KarmaConfigValue;
+    }>;
+    /** A boolean indicating if the comparison is reliable (i.e., no unsupported values were found). */
+    isReliable: boolean;
+}
+/**
+ * Generates the default Karma configuration file content as a string.
+ * @param relativePathToWorkspaceRoot The relative path from the Karma config file to the workspace root.
+ * @param projectName The name of the project.
+ * @param needDevkitPlugin A boolean indicating if the devkit plugin is needed.
+ * @returns The content of the default `karma.conf.js` file.
+ */
+export declare function generateDefaultKarmaConfig(relativePathToWorkspaceRoot: string, projectName: string, needDevkitPlugin: boolean): Promise<string>;
+/**
+ * Compares two Karma configuration analyses and returns the difference.
+ * @param projectAnalysis The analysis of the project's configuration.
+ * @param defaultAnalysis The analysis of the default configuration to compare against.
+ * @returns A diff object representing the changes between the two configurations.
+ */
+export declare function compareKarmaConfigs(projectAnalysis: KarmaConfigAnalysis, defaultAnalysis: KarmaConfigAnalysis): KarmaConfigDiff;
+/**
+ * Checks if there are any differences in the provided Karma configuration diff.
+ * @param diff The Karma configuration diff object to check.
+ * @returns True if there are any differences; false otherwise.
+ */
+export declare function hasDifferences(diff: KarmaConfigDiff): boolean;
+/**
+ * Compares a project's Karma configuration with the default configuration.
+ * @param projectConfigContent The content of the project's `karma.conf.js` file.
+ * @param projectRoot The root directory of the project.
+ * @param needDevkitPlugin A boolean indicating if the devkit plugin is needed for the default config.
+ * @param karmaConfigPath The path to the Karma configuration file, used to resolve relative paths.
+ * @returns A diff object representing the changes.
+ */
+export declare function compareKarmaConfigToDefault(projectConfigContent: string, projectName: string, karmaConfigPath: string, needDevkitPlugin: boolean): Promise<KarmaConfigDiff>;
+/**
+ * Compares a project's Karma configuration with the default configuration.
+ * @param projectAnalysis The analysis of the project's configuration.
+ * @param projectRoot The root directory of the project.
+ * @param needDevkitPlugin A boolean indicating if the devkit plugin is needed for the default config.
+ * @param karmaConfigPath The path to the Karma configuration file, used to resolve relative paths.
+ * @returns A diff object representing the changes.
+ */
+export declare function compareKarmaConfigToDefault(projectAnalysis: KarmaConfigAnalysis, projectName: string, karmaConfigPath: string, needDevkitPlugin: boolean): Promise<KarmaConfigDiff>;

package/dist/src/migrations/update-21-6-1/update-angular-cli.d.ts

@@ -0,0 +1,3 @@
+import { Tree } from '@nx/devkit';
+export declare const angularCliVersion = "~20.3.0";
+export default function (tree: Tree): Promise<void>;

package/dist/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/dist/src/migrations/update-22-3-0/set-isolated-modules.d.ts

@@ -0,0 +1,2 @@
+import { type Tree } from '@nx/devkit';
+export default function (tree: Tree): Promise<void>;

package/dist/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/dist/src/migrations/update-22-3-0/update-jest-preset-angular-setup.d.ts

@@ -0,0 +1,2 @@
+import { type Tree } from '@nx/devkit';
+export default function (tree: Tree): Promise<void>;

package/dist/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/dist/src/migrations/update-22-3-0/update-module-resolution.d.ts

@@ -0,0 +1,2 @@
+import { type Tree } from '@nx/devkit';
+export default function (tree: Tree): Promise<void>;

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

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = default_1;
+const devkit_1 = require("@nx/devkit");
+const internal_1 = require("@nx/js/internal");
+const tsconfig_utils_1 = require("../../generators/utils/tsconfig-utils");
+const targets_1 = require("../../utils/targets");
+const projects_1 = require("../utils/projects");
+// Common tsconfig file names to account for non-buildable libraries
+const KNOWN_TSCONFIG_FILES = [
+    'tsconfig.json',
+    'tsconfig.lib.json',
+    'tsconfig.spec.json',
+];
+async function default_1(tree) {
+    const uniqueTsConfigs = new Set();
+    const projects = await (0, projects_1.getProjectsFilteredByDependencies)([
+        'npm:@angular/core',
+    ]);
+    for (const graphNode of projects) {
+        const projectRoot = graphNode.data.root;
+        // Add existing known tsconfig files
+        for (const tsconfigName of KNOWN_TSCONFIG_FILES) {
+            const tsconfigPath = (0, devkit_1.joinPathFragments)(projectRoot, tsconfigName);
+            if (tree.exists(tsconfigPath)) {
+                uniqueTsConfigs.add(tsconfigPath);
+            }
+        }
+        for (const [, target] of (0, targets_1.allProjectTargets)(graphNode.data)) {
+            for (const [, options] of (0, targets_1.allTargetOptions)(target)) {
+                if (typeof options?.tsConfig === 'string' &&
+                    tree.exists(options.tsConfig) &&
+                    // Exclude tsconfig.server.json - handled by update-ssr-webpack-config migration
+                    !options.tsConfig.endsWith('tsconfig.server.json')) {
+                    uniqueTsConfigs.add(options.tsConfig);
+                }
+            }
+        }
+    }
+    for (const tsConfig of uniqueTsConfigs) {
+        updateModuleAndModuleResolution(tree, tsConfig);
+    }
+    await (0, devkit_1.formatFiles)(tree);
+}
+function updateModuleAndModuleResolution(tree, tsConfigPath) {
+    const ts = (0, internal_1.ensureTypescript)();
+    // Read the resolved compiler options from the tsconfig
+    const compilerOptions = (0, tsconfig_utils_1.readCompilerOptionsFromTsConfig)(tree, tsConfigPath);
+    // Check if both module and moduleResolution are already set correctly
+    if (compilerOptions.module === ts.ModuleKind.Preserve &&
+        compilerOptions.moduleResolution === ts.ModuleResolutionKind.Bundler) {
+        return;
+    }
+    // Ensure both module and moduleResolution are set to the correct values
+    (0, devkit_1.updateJson)(tree, tsConfigPath, (json) => {
+        json.compilerOptions ??= {};
+        json.compilerOptions.module = 'preserve';
+        json.compilerOptions.moduleResolution = 'bundler';
+        return json;
+    });
+}

package/dist/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/dist/src/migrations/update-22-3-0/update-ssr-webpack-config.d.ts

@@ -0,0 +1,2 @@
+import { type Tree } from '@nx/devkit';
+export default function (tree: Tree): Promise<void>;