diff --git a/docs/generated/manifests/nx-api.json b/docs/generated/manifests/nx-api.json index 8e345f3620..96e2f35323 100644 --- a/docs/generated/manifests/nx-api.json +++ b/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", diff --git a/docs/generated/packages-metadata.json b/docs/generated/packages-metadata.json index f4d7cff7c9..1b2b3eba02 100644 --- a/docs/generated/packages-metadata.json +++ b/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", diff --git a/docs/generated/packages/angular/executors/dev-server.json b/docs/generated/packages/angular/executors/dev-server.json index 416037746a..cc4e906d0a 100644 --- a/docs/generated/packages/angular/executors/dev-server.json +++ b/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.", - "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", + "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": "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('

Hello World!

');\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", diff --git a/packages/angular/docs/dev-server-examples.md b/packages/angular/docs/dev-server-examples.md index 494478c3f3..fa51f375a2 100644 --- a/packages/angular/docs/dev-server-examples.md +++ b/packages/angular/docs/dev-server-examples.md @@ -1,29 +1,94 @@ -##### 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" - } + "executor": "@nx/angular:webpack-browser", + "options": { + ... + "customWebpackConfig": { + "path": "apps/my-app/webpack.config.js" } + } }, "serve": { - "executor": "@nx/angular:dev-server", - "configurations": { - "production": { - "buildTarget": "appName:build:production" - }, - "development": { - "buildTarget": "appName:build:development" - } + "executor": "@nx/angular:dev-server", + "configurations": { + "production": { + "buildTarget": "my-app:build:production" }, - "defaultConfiguration": "development", + "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('

Hello World!

'); + } else { + next(); + } +}; + +export default helloWorldMiddleware; +``` + +{% /tab %} diff --git a/packages/angular/executors.json b/packages/angular/executors.json index 95a9e070a6..31c610a31c 100644 --- a/packages/angular/executors.json +++ b/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", diff --git a/packages/angular/src/builders/dev-server/schema.json b/packages/angular/src/builders/dev-server/schema.json index b45dc7c659..86e88261b5 100644 --- a/packages/angular/src/builders/dev-server/schema.json +++ b/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": [