fix(@schematics/angular): add 'update-typescript-lib' migration

alan-agius4 · alan-agius4 · commit 77741f5eec73 · 2025-09-23T21:08:39.000+02:00
This migration updates the TypeScript `lib` configuration to `es2022` or a newer version if a more modern one is already in use.

This change ensures that projects are configured to support modern ECMAScript features that are commonly used in the ecosystem and required by recent versions of Angular and its dependencies. It helps prevent compilation errors related to newer language and library features.
diff --git a/packages/schematics/angular/migrations/migration-collection.json b/packages/schematics/angular/migrations/migration-collection.json
@@ -13,6 +13,11 @@
       "version": "21.0.0",
       "factory": "./karma/migration",
       "description": "Remove any karma configuration files that only contain the default content. The default configuration is automatically available without a specific project file."
+    },
+    "update-typescript-lib": {
+      "version": "21.0.0",
+      "factory": "./update-typescript-lib/migration",
+      "description": "Updates the 'lib' property in tsconfig files to use 'es2022' or a more modern version."
     }
   }
 }
diff --git a/packages/schematics/angular/migrations/update-typescript-lib/migration.ts b/packages/schematics/angular/migrations/update-typescript-lib/migration.ts
@@ -0,0 +1,94 @@
+/**
+ * @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 { Rule, Tree } from '@angular-devkit/schematics';
+import { JSONFile } from '../../utility/json-file';
+import { getWorkspace } from '../../utility/workspace';
+
+export default function (): Rule {
+  return async (host, context) => {
+    // Workspace level tsconfig
+    if (host.exists('tsconfig.json')) {
+      updateLib(host, 'tsconfig.json');
+    }
+
+    const workspace = await getWorkspace(host);
+
+    // Find all tsconfig which are references used by builders
+    for (const [, project] of workspace.projects) {
+      for (const [targetName, target] of project.targets) {
+        if (!target.options) {
+          continue;
+        }
+
+        // Update all other known CLI builders that use a tsconfig
+        const tsConfigs = [target.options, ...Object.values(target.configurations || {})]
+          .filter((opt) => typeof opt?.tsConfig === 'string')
+          .map((opt) => (opt as { tsConfig: string }).tsConfig);
+
+        const uniqueTsConfigs = new Set(tsConfigs);
+        for (const tsConfig of uniqueTsConfigs) {
+          if (host.exists(tsConfig)) {
+            updateLib(host, tsConfig);
+          } else {
+            context.logger.warn(
+              `'${tsConfig}' referenced in the '${targetName}' target does not exist.`,
+            );
+          }
+        }
+      }
+    }
+  };
+}
+
+function updateLib(host: Tree, tsConfigPath: string): void {
+  const json = new JSONFile(host, tsConfigPath);
+  const jsonPath = ['compilerOptions', 'lib'];
+  const lib = json.get(jsonPath) as string[] | undefined;
+
+  if (!lib || !Array.isArray(lib)) {
+    return;
+  }
+
+  const esLibs = lib.filter((l) => typeof l === 'string' && l.toLowerCase().startsWith('es'));
+  const hasDom = lib.some((l) => typeof l === 'string' && l.toLowerCase() === 'dom');
+
+  if (esLibs.length === 0) {
+    return;
+  }
+
+  const esLibToVersion = new Map<string, number>();
+  for (const l of esLibs) {
+    const version = l.toLowerCase().match(/^es(next|(\d+))$/)?.[1];
+    if (version) {
+      esLibToVersion.set(l, version === 'next' ? Infinity : Number(version));
+    }
+  }
+
+  if (esLibToVersion.size === 0) {
+    return;
+  }
+
+  const latestEsLib = [...esLibToVersion.entries()].sort(([, v1], [, v2]) => v2 - v1)[0];
+  const latestVersion = latestEsLib[1];
+
+  if (hasDom) {
+    if (latestVersion <= 2022) {
+      json.remove(jsonPath);
+    }
+
+    return;
+  }
+
+  // No 'dom' with 'es' libs, so update 'es' lib.
+  if (latestVersion < 2022) {
+    const newLibs = lib.filter((l) => !esLibToVersion.has(l));
+    newLibs.push('es2022');
+    json.modify(jsonPath, newLibs);
+  }
+}
diff --git a/packages/schematics/angular/migrations/update-typescript-lib/migration_spec.ts b/packages/schematics/angular/migrations/update-typescript-lib/migration_spec.ts
@@ -0,0 +1,159 @@
+/**
+ * @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 { isJsonObject } from '@angular-devkit/core';
+import { EmptyTree } from '@angular-devkit/schematics';
+import { SchematicTestRunner, UnitTestTree } from '@angular-devkit/schematics/testing';
+import { Builders, ProjectType, WorkspaceSchema } from '../../utility/workspace-models';
+
+describe('Migration to update TypeScript lib', () => {
+  const schematicName = 'update-typescript-lib';
+
+  const schematicRunner = new SchematicTestRunner(
+    'migrations',
+    require.resolve('../migration-collection.json'),
+  );
+
+  function createJsonFile(tree: UnitTestTree, filePath: string, content: {}): void {
+    const stringifiedContent = JSON.stringify(content, undefined, 2);
+    if (tree.exists(filePath)) {
+      tree.overwrite(filePath, stringifiedContent);
+    } else {
+      tree.create(filePath, stringifiedContent);
+    }
+  }
+
+  function getCompilerOptions(tree: UnitTestTree, filePath: string): Record<string, unknown> {
+    const json = tree.readJson(filePath);
+    if (isJsonObject(json) && isJsonObject(json.compilerOptions)) {
+      return json.compilerOptions;
+    }
+
+    throw new Error(`Cannot retrieve 'compilerOptions'.`);
+  }
+
+  function createWorkSpaceConfig(tree: UnitTestTree) {
+    const angularConfig: WorkspaceSchema = {
+      version: 1,
+      projects: {
+        app: {
+          root: '',
+          sourceRoot: 'src',
+          projectType: ProjectType.Application,
+          prefix: 'app',
+          architect: {
+            build: {
+              builder: Builders.Browser,
+              options: {
+                tsConfig: 'src/tsconfig.app.json',
+                main: '',
+                polyfills: '',
+              },
+              configurations: {
+                production: {
+                  tsConfig: 'src/tsconfig.app.prod.json',
+                },
+              },
+            },
+            test: {
+              builder: Builders.Karma,
+              options: {
+                karmaConfig: '',
+                tsConfig: 'src/tsconfig.spec.json',
+              },
+            },
+          },
+        },
+      },
+    };
+
+    createJsonFile(tree, 'angular.json', angularConfig);
+  }
+
+  let tree: UnitTestTree;
+  beforeEach(() => {
+    tree = new UnitTestTree(new EmptyTree());
+    createWorkSpaceConfig(tree);
+
+    // Create tsconfigs
+    const compilerOptions = { lib: ['es2020', 'dom'] };
+    const configWithExtends = { extends: './tsconfig.json', compilerOptions };
+
+    // Workspace
+    createJsonFile(tree, 'tsconfig.json', { compilerOptions });
+
+    // Application
+    createJsonFile(tree, 'src/tsconfig.app.json', configWithExtends);
+    createJsonFile(tree, 'src/tsconfig.app.prod.json', configWithExtends);
+    createJsonFile(tree, 'src/tsconfig.spec.json', { compilerOptions });
+  });
+
+  it(`should remove 'lib' when 'dom' is present and ES version is less than 2022`, async () => {
+    const newTree = await schematicRunner.runSchematic(schematicName, {}, tree);
+    const compilerOptions = getCompilerOptions(newTree, 'tsconfig.json');
+    expect(compilerOptions.lib).toBeUndefined();
+  });
+
+  it(`should remove 'lib' when 'dom' is present and ES version is 2022`, async () => {
+    createJsonFile(tree, 'tsconfig.json', { compilerOptions: { lib: ['es2022', 'dom'] } });
+    const newTree = await schematicRunner.runSchematic(schematicName, {}, tree);
+    const compilerOptions = getCompilerOptions(newTree, 'tsconfig.json');
+    expect(compilerOptions.lib).toBeUndefined();
+  });
+
+  it(`should not remove 'lib' when 'dom' is present and ES version is 'esnext'`, async () => {
+    createJsonFile(tree, 'tsconfig.json', { compilerOptions: { lib: ['esnext', 'dom'] } });
+    const newTree = await schematicRunner.runSchematic(schematicName, {}, tree);
+    const compilerOptions = getCompilerOptions(newTree, 'tsconfig.json');
+    expect(compilerOptions.lib).toEqual(['esnext', 'dom']);
+  });
+
+  it(`should update 'lib' to 'es2022' when 'dom' is not present and ES version is less than 2022`, async () => {
+    createJsonFile(tree, 'tsconfig.json', { compilerOptions: { lib: ['es2020'] } });
+    const newTree = await schematicRunner.runSchematic(schematicName, {}, tree);
+    const compilerOptions = getCompilerOptions(newTree, 'tsconfig.json');
+    expect(compilerOptions.lib).toEqual(['es2022']);
+  });
+
+  it(`should not update 'lib' when 'dom' is not present and ES version is 2022`, async () => {
+    createJsonFile(tree, 'tsconfig.json', { compilerOptions: { lib: ['es2022'] } });
+    const newTree = await schematicRunner.runSchematic(schematicName, {}, tree);
+    const compilerOptions = getCompilerOptions(newTree, 'tsconfig.json');
+    expect(compilerOptions.lib).toEqual(['es2022']);
+  });
+
+  it(`should not update 'lib' when 'dom' is not present and ES version is 'esnext'`, async () => {
+    createJsonFile(tree, 'tsconfig.json', { compilerOptions: { lib: ['esnext'] } });
+    const newTree = await schematicRunner.runSchematic(schematicName, {}, tree);
+    const compilerOptions = getCompilerOptions(newTree, 'tsconfig.json');
+    expect(compilerOptions.lib).toEqual(['esnext']);
+  });
+
+  it('should not error when a tsconfig is not found', async () => {
+    tree.delete('src/tsconfig.spec.json');
+    await schematicRunner.runSchematic(schematicName, {}, tree);
+  });
+
+  it('should not error when compilerOptions is not defined', async () => {
+    createJsonFile(tree, 'tsconfig.json', {});
+    await schematicRunner.runSchematic(schematicName, {}, tree);
+  });
+
+  it(`should not error when 'lib' is not defined`, async () => {
+    createJsonFile(tree, 'tsconfig.json', { compilerOptions: {} });
+    await schematicRunner.runSchematic(schematicName, {}, tree);
+  });
+
+  it(`should remove 'lib' from all tsconfigs`, async () => {
+    const newTree = await schematicRunner.runSchematic(schematicName, {}, tree);
+    expect(getCompilerOptions(newTree, 'tsconfig.json').lib).toBeUndefined();
+    expect(getCompilerOptions(newTree, 'src/tsconfig.app.json').lib).toBeUndefined();
+    expect(getCompilerOptions(newTree, 'src/tsconfig.app.prod.json').lib).toBeUndefined();
+    expect(getCompilerOptions(newTree, 'src/tsconfig.spec.json').lib).toBeUndefined();
+  });
+});

Original file line number	Diff line number	Diff line change
`@@ -13,6 +13,11 @@`
`13`	`13`	`"version": "21.0.0",`
`14`	`14`	`"factory": "./karma/migration",`
`15`	`15`	`"description": "Remove any karma configuration files that only contain the default content. The default configuration is automatically available without a specific project file."`
	`16`	`+ },`
	`17`	`+ "update-typescript-lib": {`
	`18`	`+ "version": "21.0.0",`
	`19`	`+ "factory": "./update-typescript-lib/migration",`
	`20`	`+ "description": "Updates the 'lib' property in tsconfig files to use 'es2022' or a more modern version."`
`16`	`21`	`}`
`17`	`22`	`}`
`18`	`23`	`}`