docs(angular): improve dev-server executor docs (#21434)

docs/generated/manifests/nx-api.json

@@ -95,7 +95,7 @@
         "type": "executor"
       },
       "/nx-api/angular/executors/dev-server": {
-        "description": "The `dev-server` executor is very similar to the standard `dev-server` builder provided by the Angular Devkit. It is usually used in tandem with `@nrwl/angular:webpack-browser` when your Angular application uses a custom webpack configuration.",
+        "description": "Serves an Angular application using [Webpack](https://webpack.js.org/) when the build target is using a Webpack-based executor, or [Vite](https://vitejs.dev/) when the build target uses an esbuild-based executor.",
         "file": "generated/packages/angular/executors/dev-server.json",
         "hidden": false,
         "name": "dev-server",

docs/generated/packages-metadata.json

@@ -90,7 +90,7 @@
         "type": "executor"
       },
       {
-        "description": "The `dev-server` executor is very similar to the standard `dev-server` builder provided by the Angular Devkit. It is usually used in tandem with `@nrwl/angular:webpack-browser` when your Angular application uses a custom webpack configuration.",
+        "description": "Serves an Angular application using [Webpack](https://webpack.js.org/) when the build target is using a Webpack-based executor, or [Vite](https://vitejs.dev/) when the build target uses an esbuild-based executor.",
         "file": "generated/packages/angular/executors/dev-server.json",
         "hidden": false,
         "name": "dev-server",

docs/generated/packages/angular/executors/dev-server.json

@@ -6,8 +6,8 @@
     "outputCapture": "direct-nodejs",
     "$schema": "http://json-schema.org/draft-07/schema",
     "title": "Schema for Webpack Dev Server",
-    "description": "The dev-server executor is very similar to the standard dev server builder provided by the Angular Devkit. It is usually used in tandem with `@nx/angular:webpack-browser` when your Angular application uses a custom webpack configuration.",
+    "description": "Serves an Angular application using [Webpack](https://webpack.js.org/) when the build target is using a Webpack-based executor, or [Vite](https://vitejs.dev/) when the build target uses an esbuild-based executor.",
-    "examplesFile": "##### Seving an application with a custom webpack configuration\n\nThis executor should be used along with `@nx/angular:webpack-browser` to serve an application using a custom webpack configuration.\n\nYour `project.json` file should contain a `build` and `serve` target that matches the following:\n\n```json\n\"build\": {\n    \"executor\": \"@nx/angular:webpack-browser\",\n    \"options\": {\n        ...\n        \"customWebpackConfig\": {\n          \"path\": \"apps/appName/webpack.config.js\"\n        }\n    }\n},\n\"serve\": {\n    \"executor\": \"@nx/angular:dev-server\",\n    \"configurations\": {\n        \"production\": {\n            \"buildTarget\": \"appName:build:production\"\n        },\n        \"development\": {\n            \"buildTarget\": \"appName:build:development\"\n        }\n    },\n    \"defaultConfiguration\": \"development\",\n}\n```\n",
+    "examplesFile": "The `@nx/angular:dev-server` executor is very similar to the `@angular-devkit/build-angular:dev-server` builder provided by the Angular CLI. In addition to the features provided by the Angular CLI builder, the `@nx/angular:dev-server` executor also supports the following:\n\n- Best integration for `@nx/angular:webpack-browser`, `@nx/angular:browser-esbuild` and `@nx/angular:application`\n- Providing HTTP request middleware functions when the build target is using an esbuild-based executor\n- Incremental builds\n\n## Examples\n\n{% tabs %}\n{% tab label=\"Using a custom Webpack configuration\" %}\n\nThis executor should be used along with `@nx/angular:webpack-browser` to serve an application using a custom Webpack configuration.\n\nAdd the `serve` target using the `@nx/angular:dev-server` executor, set the `build` target executor as `@nx/angular:webpack-browser` and set the `customWebpackConfig` option as shown below:\n\n```json {% fileName=\"apps/my-app/project.json\" highlightLines=[2,\"5-7\",\"10-20\"] %}\n\"build\": {\n  \"executor\": \"@nx/angular:webpack-browser\",\n  \"options\": {\n    ...\n    \"customWebpackConfig\": {\n      \"path\": \"apps/my-app/webpack.config.js\"\n    }\n  }\n},\n\"serve\": {\n  \"executor\": \"@nx/angular:dev-server\",\n  \"configurations\": {\n    \"production\": {\n      \"buildTarget\": \"my-app:build:production\"\n    },\n    \"development\": {\n      \"buildTarget\": \"my-app:build:development\"\n    }\n  },\n  \"defaultConfiguration\": \"development\",\n}\n```\n\n```js {% fileName=\"apps/my-app/webpack.config.js\" %}\nmodule.exports = (config) => {\n  // update the config with your custom configuration\n\n  return config;\n};\n```\n\n{% /tab %}\n\n{% tab label=\"Providing HTTP request middleware function\" %}\n\n{% callout type=\"warning\" title=\"Overrides\" }\n\nAvailable for workspaces using Angular version 17.0.0 or greater and with `build` targets using an esbuild-based executor.\n\n{% /callout %}\n\nThe executor accepts an `esbuildMidleware` option that allows you to provide HTTP require middleware functions that will be used by the Vite development server.\n\n```json {% fileName=\"apps/my-app/project.json\" highlightLines=[8] %}\n{\n  ...\n  \"targets\": {\n    \"serve\": {\n      \"executor\": \"@nx/angular:dev-server\",\n      \"options\": {\n        ...\n        \"esbuildMidleware\": [\"apps/my-app/hello-world.middleware.ts\"]\n      }\n    }\n    ...\n  }\n}\n```\n\n```ts {% fileName=\"apps/my-app/hello-world.middleware.ts\" %}\nimport type { IncomingMessage, ServerResponse } from 'node:http';\n\nconst helloWorldMiddleware = (\n  req: IncomingMessage,\n  res: ServerResponse,\n  next: (err?: unknown) => void\n) => {\n  if (req.url === '/hello-world') {\n    res.end('<h1>Hello World!</h1>');\n  } else {\n    next();\n  }\n};\n\nexport default helloWorldMiddleware;\n```\n\n{% /tab %}\n",
     "type": "object",
     "presets": [
       { "name": "Using a Different Port", "keys": ["buildTarget", "port"] }
@@ -125,7 +125,7 @@
       { "required": ["browserTarget"] }
     ]
   },
-  "description": "The `dev-server` executor is very similar to the standard `dev-server` builder provided by the Angular Devkit. It is usually used in tandem with `@nrwl/angular:webpack-browser` when your Angular application uses a custom webpack configuration.",
+  "description": "Serves an Angular application using [Webpack](https://webpack.js.org/) when the build target is using a Webpack-based executor, or [Vite](https://vitejs.dev/) when the build target uses an esbuild-based executor.",
   "aliases": [],
   "hidden": false,
   "path": "/packages/angular/src/builders/dev-server/schema.json",

packages/angular/docs/dev-server-examples.md

@@ -1,16 +1,25 @@
-##### Seving an application with a custom webpack configuration
+The `@nx/angular:dev-server` executor is very similar to the `@angular-devkit/build-angular:dev-server` builder provided by the Angular CLI. In addition to the features provided by the Angular CLI builder, the `@nx/angular:dev-server` executor also supports the following:
 
-This executor should be used along with `@nx/angular:webpack-browser` to serve an application using a custom webpack configuration.
+- Best integration for `@nx/angular:webpack-browser`, `@nx/angular:browser-esbuild` and `@nx/angular:application`
+- Providing HTTP request middleware functions when the build target is using an esbuild-based executor
+- Incremental builds
 
-Your `project.json` file should contain a `build` and `serve` target that matches the following:
+## Examples
 
-```json
+{% tabs %}
+{% tab label="Using a custom Webpack configuration" %}
+
+This executor should be used along with `@nx/angular:webpack-browser` to serve an application using a custom Webpack configuration.
+
+Add the `serve` target using the `@nx/angular:dev-server` executor, set the `build` target executor as `@nx/angular:webpack-browser` and set the `customWebpackConfig` option as shown below:
+
+```json {% fileName="apps/my-app/project.json" highlightLines=[2,"5-7","10-20"] %}
 "build": {
   "executor": "@nx/angular:webpack-browser",
   "options": {
     ...
     "customWebpackConfig": {
-          "path": "apps/appName/webpack.config.js"
+      "path": "apps/my-app/webpack.config.js"
     }
   }
 },
@@ -18,12 +27,68 @@ Your `project.json` file should contain a `build` and `serve` target that matche
   "executor": "@nx/angular:dev-server",
   "configurations": {
     "production": {
-            "buildTarget": "appName:build:production"
+      "buildTarget": "my-app:build:production"
     },
     "development": {
-            "buildTarget": "appName:build:development"
+      "buildTarget": "my-app:build:development"
     }
   },
   "defaultConfiguration": "development",
 }
 ```
+
+```js {% fileName="apps/my-app/webpack.config.js" %}
+module.exports = (config) => {
+  // update the config with your custom configuration
+
+  return config;
+};
+```
+
+{% /tab %}
+
+{% tab label="Providing HTTP request middleware function" %}
+
+{% callout type="warning" title="Overrides" }
+
+Available for workspaces using Angular version 17.0.0 or greater and with `build` targets using an esbuild-based executor.
+
+{% /callout %}
+
+The executor accepts an `esbuildMidleware` option that allows you to provide HTTP require middleware functions that will be used by the Vite development server.
+
+```json {% fileName="apps/my-app/project.json" highlightLines=[8] %}
+{
+  ...
+  "targets": {
+    "serve": {
+      "executor": "@nx/angular:dev-server",
+      "options": {
+        ...
+        "esbuildMidleware": ["apps/my-app/hello-world.middleware.ts"]
+      }
+    }
+    ...
+  }
+}
+```
+
+```ts {% fileName="apps/my-app/hello-world.middleware.ts" %}
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+const helloWorldMiddleware = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  next: (err?: unknown) => void
+) => {
+  if (req.url === '/hello-world') {
+    res.end('<h1>Hello World!</h1>');
+  } else {
+    next();
+  }
+};
+
+export default helloWorldMiddleware;
+```
+
+{% /tab %}

packages/angular/executors.json

@@ -40,7 +40,7 @@
     "dev-server": {
       "implementation": "./src/builders/dev-server/dev-server.impl",
       "schema": "./src/builders/dev-server/schema.json",
-      "description": "The `dev-server` executor is very similar to the standard `dev-server` builder provided by the Angular Devkit. It is usually used in tandem with `@nrwl/angular:webpack-browser` when your Angular application uses a custom webpack configuration."
+      "description": "Serves an Angular application using [Webpack](https://webpack.js.org/) when the build target is using a Webpack-based executor, or [Vite](https://vitejs.dev/) when the build target uses an esbuild-based executor."
     },
     "webpack-server": {
       "implementation": "./src/builders/webpack-server/webpack-server.impl",

packages/angular/src/builders/dev-server/schema.json

@@ -3,7 +3,7 @@
   "outputCapture": "direct-nodejs",
   "$schema": "http://json-schema.org/draft-07/schema",
   "title": "Schema for Webpack Dev Server",
-  "description": "The dev-server executor is very similar to the standard dev server builder provided by the Angular Devkit. It is usually used in tandem with `@nx/angular:webpack-browser` when your Angular application uses a custom webpack configuration.",
+  "description": "Serves an Angular application using [Webpack](https://webpack.js.org/) when the build target is using a Webpack-based executor, or [Vite](https://vitejs.dev/) when the build target uses an esbuild-based executor.",
   "examplesFile": "../../../docs/dev-server-examples.md",
   "type": "object",
   "presets": [