fix(angular): update schema and validate compatibility in esbuild-based executors (#20564)

docs/generated/manifests/nx-api.json

@@ -77,7 +77,7 @@
         "type": "executor"
       },
       "/nx-api/angular/executors/application": {
-        "description": "Builds an application with esbuild with support for incremental builds.",
+        "description": "Builds an application with esbuild with support for incremental builds. _Note: this is only supported in Angular versions >= 17.0.0_.",
         "file": "generated/packages/angular/executors/application.json",
         "hidden": false,
         "name": "application",

docs/generated/packages-metadata.json

@@ -72,7 +72,7 @@
         "type": "executor"
       },
       {
-        "description": "Builds an application with esbuild with support for incremental builds.",
+        "description": "Builds an application with esbuild with support for incremental builds. _Note: this is only supported in Angular versions >= 17.0.0_.",
         "file": "generated/packages/angular/executors/application.json",
         "hidden": false,
         "name": "application",

docs/generated/packages/angular/executors/application.json

@@ -4,7 +4,7 @@
   "schema": {
     "$schema": "http://json-schema.org/draft-07/schema",
     "title": "Schema for Nx Application Executor",
-    "description": "Builds an application with esbuild with support for incremental builds.",
+    "description": "Builds an application with esbuild with support for incremental builds. _Note: this is only supported in Angular versions >= 17.0.0_.",
     "examplesFile": "The `@nx/angular:application` executor is very similar to the `@angular-devkit/build-angular:application` builder provided by the Angular CLI. It builds an Angular application using [esbuild](https://esbuild.github.io/) with integrated SSR and prerendering capabilities.\n\nIn addition to the features provided by the Angular CLI builder, the `@nx/angular:application` executor also supports the following:\n\n- Providing esbuild plugins\n- Incremental builds\n\n## Examples\n\n{% tabs %}\n{% tab label=\"Providing esbuild plugins\" %}\n\nThe executor accepts a `plugins` option that allows you to provide esbuild plugins that will be used when building your application. It allows providing a path to a plugin file or an object with a `path` and `options` property to provide options to the plugin.\n\n```json\n\"build\": {\n  \"executor\": \"@nx/angular:application\",\n  \"options\": {\n    ...\n    \"plugins\": [\n      \"apps/my-app/plugins/plugin1.js\",\n      {\n        \"path\": \"apps/my-app/plugins/plugin2.js\",\n        \"options\": {\n          \"someOption\": \"someValue\"\n        }\n      }\n    ]\n  }\n}\n```\n\n{% /tab %}\n{% /tabs %}\n",
     "outputCapture": "direct-nodejs",
     "type": "object",
@@ -191,11 +191,6 @@
                         "type": "boolean",
                         "description": "Extract and inline critical CSS definitions to improve first paint time.",
                         "default": true
-                      },
-                      "removeSpecialComments": {
-                        "type": "boolean",
-                        "description": "Remove comments in global CSS that contains '@license' or '@preserve' or that starts with '//!' or '/*!'.",
-                        "default": true
                       }
                     },
                     "additionalProperties": false
@@ -227,13 +222,6 @@
           { "type": "boolean" }
         ]
       },
-      "loader": {
-        "description": "Defines the type of loader to use with a specified file extension when used with a JavaScript `import`. `text` inlines the content as a string; `binary` inlines the content as a Uint8Array; `file` emits the file and provides the runtime location of the file; `empty` considers the content to be empty and not include it in bundles.",
-        "type": "object",
-        "patternProperties": {
-          "^\\.\\S+$": { "enum": ["text", "binary", "file", "empty"] }
-        }
-      },
       "fileReplacements": {
         "description": "Replace compilation source files with other compilation source files in the build.",
         "type": "array",
@@ -685,7 +673,7 @@
     },
     "presets": []
   },
-  "description": "Builds an application with esbuild with support for incremental builds.",
+  "description": "Builds an application with esbuild with support for incremental builds. _Note: this is only supported in Angular versions >= 17.0.0_.",
   "aliases": [],
   "hidden": false,
   "path": "/packages/angular/src/executors/application/schema.json",

docs/generated/packages/angular/executors/browser-esbuild.json

@@ -516,7 +516,7 @@
         "default": true
       },
       "plugins": {
-        "description": "A list of ESBuild plugins.",
+        "description": "A list of ESBuild plugins. _Note: this is only supported in Angular versions >= 17.0.0_.",
         "type": "array",
         "items": {
           "oneOf": [

packages/angular/executors.json

@@ -28,7 +28,7 @@
     "application": {
       "implementation": "./src/executors/application/application.impl",
       "schema": "./src/executors/application/schema.json",
-      "description": "Builds an application with esbuild with support for incremental builds."
+      "description": "Builds an application with esbuild with support for incremental builds. _Note: this is only supported in Angular versions >= 17.0.0_."
     }
   },
   "builders": {

packages/angular/src/executors/application/application.impl.ts

@@ -1,6 +1,7 @@
 import type { ExecutorContext } from '@nx/devkit';
 import type { DependentBuildableProjectNode } from '@nx/js/src/utils/buildable-libs-utils';
 import { createBuilderContext } from 'nx/src/adapter/ngcli-adapter';
+import { getInstalledAngularVersionInfo } from '../utilities/angular-version-utils';
 import { createTmpTsConfigForBuildableLibs } from '../utilities/buildable-libs';
 import { loadPlugins } from '../utilities/esbuild-extensions';
 import type { ApplicationExecutorOptions } from './schema';
@@ -9,6 +10,14 @@ export default async function* applicationExecutor(
   options: ApplicationExecutorOptions,
   context: ExecutorContext
 ) {
+  const { major: angularMajorVersion, version: angularVersion } =
+    getInstalledAngularVersionInfo();
+  if (angularMajorVersion < 17) {
+    throw new Error(
+      `The "application" executor requires Angular version 17 or greater. You are currently using version ${angularVersion}.`
+    );
+  }
+
   const {
     buildLibsFromSource = true,
     plugins: pluginPaths,

packages/angular/src/executors/application/schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema",
   "title": "Schema for Nx Application Executor",
-  "description": "Builds an application with esbuild with support for incremental builds.",
+  "description": "Builds an application with esbuild with support for incremental builds. _Note: this is only supported in Angular versions >= 17.0.0_.",
   "examplesFile": "../../../docs/application-executor-examples.md",
   "outputCapture": "direct-nodejs",
   "type": "object",
@@ -164,11 +164,6 @@
                       "type": "boolean",
                       "description": "Extract and inline critical CSS definitions to improve first paint time.",
                       "default": true
-                    },
-                    "removeSpecialComments": {
-                      "type": "boolean",
-                      "description": "Remove comments in global CSS that contains '@license' or '@preserve' or that starts with '//!' or '/*!'.",
-                      "default": true
                     }
                   },
                   "additionalProperties": false
@@ -206,13 +201,6 @@
         }
       ]
     },
-    "loader": {
-      "description": "Defines the type of loader to use with a specified file extension when used with a JavaScript `import`. `text` inlines the content as a string; `binary` inlines the content as a Uint8Array; `file` emits the file and provides the runtime location of the file; `empty` considers the content to be empty and not include it in bundles.",
-      "type": "object",
-      "patternProperties": {
-        "^\\.\\S+$": { "enum": ["text", "binary", "file", "empty"] }
-      }
-    },
     "fileReplacements": {
       "description": "Replace compilation source files with other compilation source files in the build.",
       "type": "array",

packages/angular/src/executors/browser-esbuild/browser-esbuild.impl.ts

@@ -1,6 +1,7 @@
-import type { ExecutorContext } from '@nx/devkit';
+import { stripIndents, type ExecutorContext } from '@nx/devkit';
 import type { DependentBuildableProjectNode } from '@nx/js/src/utils/buildable-libs-utils';
 import { createBuilderContext } from 'nx/src/adapter/ngcli-adapter';
+import { getInstalledAngularVersionInfo } from '../utilities/angular-version-utils';
 import { createTmpTsConfigForBuildableLibs } from '../utilities/buildable-libs';
 import { loadPlugins } from '../utilities/esbuild-extensions';
 import type { EsBuildSchema } from './schema';
@@ -9,6 +10,15 @@ export default async function* esbuildExecutor(
   options: EsBuildSchema,
   context: ExecutorContext
 ) {
+  if (options.plugins) {
+    const { major: angularMajorVersion, version: angularVersion } =
+      getInstalledAngularVersionInfo();
+    if (angularMajorVersion < 17) {
+      throw new Error(stripIndents`The "plugins" option is only supported in Angular >= 17.0.0. You are currently using "${angularVersion}".
+        You can resolve this error by removing the "plugins" option or by migrating to Angular 17.0.0.`);
+    }
+  }
+
   options.buildLibsFromSource ??= true;
 
   const {

packages/angular/src/executors/browser-esbuild/schema.json

@@ -444,7 +444,7 @@
       "default": true
     },
     "plugins": {
-      "description": "A list of ESBuild plugins.",
+      "description": "A list of ESBuild plugins. _Note: this is only supported in Angular versions >= 17.0.0_.",
       "type": "array",
       "items": {
         "oneOf": [