diff --git a/docs/generated/manifests/nx-api.json b/docs/generated/manifests/nx-api.json index c9a90de386..746747f3e1 100644 --- a/docs/generated/manifests/nx-api.json +++ b/docs/generated/manifests/nx-api.json @@ -63,7 +63,7 @@ "type": "executor" }, "/nx-api/angular/executors/ng-packagr-lite": { - "description": "Builds a library with support for incremental builds.\nThis executor is meant to be used with buildable libraries in an incremental build scenario. It is similar to the `@nrwl/angular:package` executor but with some key differences:\n- It doesn't run `ngcc` automatically (`ngcc` needs to be run separately beforehand if needed, this can be done in a `postinstall` hook on `package.json`).\n- It only produces ESM2020 bundles.\n- It doesn't generate package exports in the `package.json`.", + "description": "Builds an Angular library with support for incremental builds.\n\nThis executor is meant to be used with buildable libraries in an incremental build scenario. It is similar to the `@nx/angular:package` executor but with some key differences:\n- For supported Angular versions lower than v16, it doesn't run `ngcc` automatically (`ngcc` is no longer available from Angular v16 onwards, for lower versions, it needs to be run separately beforehand if needed, this can be done in a `postinstall` hook on `package.json`).\n- It only produces ESM2022 bundles (ESM2020 for supported Angular versions lower than v16).", "file": "generated/packages/angular/executors/ng-packagr-lite.json", "hidden": false, "name": "ng-packagr-lite", @@ -72,7 +72,7 @@ "type": "executor" }, "/nx-api/angular/executors/package": { - "description": "Builds and packages an Angular library producing an output following the Angular Package Format (APF) to be distributed as an NPM package.\nThis executor is similar to the `@angular-devkit/build-angular:ng-packagr` with additional support for incremental builds.", + "description": "Builds and packages an Angular library producing an output following the Angular Package Format (APF) to be distributed as an NPM package.\n\nThis executor is a drop-in replacement for the `@angular-devkit/build-angular:ng-packagr` with additional support for incremental builds.", "file": "generated/packages/angular/executors/package.json", "hidden": false, "name": "package", @@ -81,7 +81,7 @@ "type": "executor" }, "/nx-api/angular/executors/browser-esbuild": { - "description": "Builds your application with esbuild and adds support for incremental builds.", + "description": "Builds an Angular application using [esbuild](https://esbuild.github.io/).", "file": "generated/packages/angular/executors/browser-esbuild.json", "hidden": false, "name": "browser-esbuild", @@ -90,7 +90,7 @@ "type": "executor" }, "/nx-api/angular/executors/module-federation-dev-server": { - "description": "The module-federation-dev-server executor is reserved exclusively for use with host Module Federation applications. It allows the user to specify which remote applications should be served with the host.", + "description": "Serves host [Module Federation](https://module-federation.io/) applications ([webpack](https://webpack.js.org/)-based) allowing to specify which remote applications should be served with the host.", "file": "generated/packages/angular/executors/module-federation-dev-server.json", "hidden": false, "name": "module-federation-dev-server", @@ -99,7 +99,7 @@ "type": "executor" }, "/nx-api/angular/executors/application": { - "description": "Builds an application with esbuild with support for incremental builds. _Note: this is only supported in Angular versions >= 17.0.0_.", + "description": "Builds an Angular application using [esbuild](https://esbuild.github.io/) with integrated SSR and prerendering capabilities. _Note: this is only supported in Angular versions >= 17.0.0_.", "file": "generated/packages/angular/executors/application.json", "hidden": false, "name": "application", @@ -117,7 +117,7 @@ "type": "executor" }, "/nx-api/angular/executors/webpack-browser": { - "description": "The `webpack-browser` executor is very similar to the standard `browser` builder provided by the Angular Devkit. It allows you to build your Angular application to a build artifact that can be hosted online. There are some key differences: \n- Supports Custom Webpack Configurations \n- Supports Incremental Building", + "description": "Builds an Angular application using [webpack](https://webpack.js.org/).", "file": "generated/packages/angular/executors/webpack-browser.json", "hidden": false, "name": "webpack-browser", @@ -126,7 +126,7 @@ "type": "executor" }, "/nx-api/angular/executors/dev-server": { - "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.", + "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](https://esbuild.github.io/)-based executor.", "file": "generated/packages/angular/executors/dev-server.json", "hidden": false, "name": "dev-server", @@ -135,7 +135,7 @@ "type": "executor" }, "/nx-api/angular/executors/webpack-server": { - "description": "The `webpack-server` executor is very similar to the standard `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 and NgUniversal for SSR.", + "description": "Builds a server Angular application using [webpack](https://webpack.js.org/). This executor is a drop-in replacement for the `@angular-devkit/build-angular:server` builder provided by the Angular CLI. It is usually used in tandem with the `@nx/angular:webpack-browser` executor when your Angular application uses a custom webpack configuration.", "file": "generated/packages/angular/executors/webpack-server.json", "hidden": false, "name": "webpack-server", @@ -144,7 +144,7 @@ "type": "executor" }, "/nx-api/angular/executors/module-federation-dev-ssr": { - "description": "The module-federation-dev-ssr executor is reserved exclusively for use with host Module Federation applications that use SSR. It allows the user to specify which remote applications should be served with the host.", + "description": "Serves host [Module Federation](https://module-federation.io/) applications ([webpack](https://webpack.js.org/)-based) that use SSR allowing to specify which remote applications should be served with the host.", "file": "generated/packages/angular/executors/module-federation-dev-ssr.json", "hidden": false, "name": "module-federation-dev-ssr", diff --git a/docs/generated/packages-metadata.json b/docs/generated/packages-metadata.json index 527f9f06e5..587f550f52 100644 --- a/docs/generated/packages-metadata.json +++ b/docs/generated/packages-metadata.json @@ -58,7 +58,7 @@ "type": "executor" }, { - "description": "Builds a library with support for incremental builds.\nThis executor is meant to be used with buildable libraries in an incremental build scenario. It is similar to the `@nrwl/angular:package` executor but with some key differences:\n- It doesn't run `ngcc` automatically (`ngcc` needs to be run separately beforehand if needed, this can be done in a `postinstall` hook on `package.json`).\n- It only produces ESM2020 bundles.\n- It doesn't generate package exports in the `package.json`.", + "description": "Builds an Angular library with support for incremental builds.\n\nThis executor is meant to be used with buildable libraries in an incremental build scenario. It is similar to the `@nx/angular:package` executor but with some key differences:\n- For supported Angular versions lower than v16, it doesn't run `ngcc` automatically (`ngcc` is no longer available from Angular v16 onwards, for lower versions, it needs to be run separately beforehand if needed, this can be done in a `postinstall` hook on `package.json`).\n- It only produces ESM2022 bundles (ESM2020 for supported Angular versions lower than v16).", "file": "generated/packages/angular/executors/ng-packagr-lite.json", "hidden": false, "name": "ng-packagr-lite", @@ -67,7 +67,7 @@ "type": "executor" }, { - "description": "Builds and packages an Angular library producing an output following the Angular Package Format (APF) to be distributed as an NPM package.\nThis executor is similar to the `@angular-devkit/build-angular:ng-packagr` with additional support for incremental builds.", + "description": "Builds and packages an Angular library producing an output following the Angular Package Format (APF) to be distributed as an NPM package.\n\nThis executor is a drop-in replacement for the `@angular-devkit/build-angular:ng-packagr` with additional support for incremental builds.", "file": "generated/packages/angular/executors/package.json", "hidden": false, "name": "package", @@ -76,7 +76,7 @@ "type": "executor" }, { - "description": "Builds your application with esbuild and adds support for incremental builds.", + "description": "Builds an Angular application using [esbuild](https://esbuild.github.io/).", "file": "generated/packages/angular/executors/browser-esbuild.json", "hidden": false, "name": "browser-esbuild", @@ -85,7 +85,7 @@ "type": "executor" }, { - "description": "The module-federation-dev-server executor is reserved exclusively for use with host Module Federation applications. It allows the user to specify which remote applications should be served with the host.", + "description": "Serves host [Module Federation](https://module-federation.io/) applications ([webpack](https://webpack.js.org/)-based) allowing to specify which remote applications should be served with the host.", "file": "generated/packages/angular/executors/module-federation-dev-server.json", "hidden": false, "name": "module-federation-dev-server", @@ -94,7 +94,7 @@ "type": "executor" }, { - "description": "Builds an application with esbuild with support for incremental builds. _Note: this is only supported in Angular versions >= 17.0.0_.", + "description": "Builds an Angular application using [esbuild](https://esbuild.github.io/) with integrated SSR and prerendering capabilities. _Note: this is only supported in Angular versions >= 17.0.0_.", "file": "generated/packages/angular/executors/application.json", "hidden": false, "name": "application", @@ -112,7 +112,7 @@ "type": "executor" }, { - "description": "The `webpack-browser` executor is very similar to the standard `browser` builder provided by the Angular Devkit. It allows you to build your Angular application to a build artifact that can be hosted online. There are some key differences: \n- Supports Custom Webpack Configurations \n- Supports Incremental Building", + "description": "Builds an Angular application using [webpack](https://webpack.js.org/).", "file": "generated/packages/angular/executors/webpack-browser.json", "hidden": false, "name": "webpack-browser", @@ -121,7 +121,7 @@ "type": "executor" }, { - "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.", + "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](https://esbuild.github.io/)-based executor.", "file": "generated/packages/angular/executors/dev-server.json", "hidden": false, "name": "dev-server", @@ -130,7 +130,7 @@ "type": "executor" }, { - "description": "The `webpack-server` executor is very similar to the standard `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 and NgUniversal for SSR.", + "description": "Builds a server Angular application using [webpack](https://webpack.js.org/). This executor is a drop-in replacement for the `@angular-devkit/build-angular:server` builder provided by the Angular CLI. It is usually used in tandem with the `@nx/angular:webpack-browser` executor when your Angular application uses a custom webpack configuration.", "file": "generated/packages/angular/executors/webpack-server.json", "hidden": false, "name": "webpack-server", @@ -139,7 +139,7 @@ "type": "executor" }, { - "description": "The module-federation-dev-ssr executor is reserved exclusively for use with host Module Federation applications that use SSR. It allows the user to specify which remote applications should be served with the host.", + "description": "Serves host [Module Federation](https://module-federation.io/) applications ([webpack](https://webpack.js.org/)-based) that use SSR allowing to specify which remote applications should be served with the host.", "file": "generated/packages/angular/executors/module-federation-dev-ssr.json", "hidden": false, "name": "module-federation-dev-ssr", diff --git a/docs/generated/packages/angular/executors/application.json b/docs/generated/packages/angular/executors/application.json index bd95339ac3..825934a263 100644 --- a/docs/generated/packages/angular/executors/application.json +++ b/docs/generated/packages/angular/executors/application.json @@ -4,8 +4,8 @@ "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. _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- Providing a function to transform the application's `index.html` file\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 {% fileName=\"apps/my-app/project.json\" highlightLines=[\"8-16\"] %}\n{\n ...\n \"targets\": {\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\": \"some value\"\n }\n }\n ]\n }\n }\n ...\n }\n}\n```\n\n```ts {% fileName=\"apps/my-app/plugins/plugin1.js\" %}\nconst plugin1 = {\n name: 'plugin1',\n setup(build) {\n const options = build.initialOptions;\n options.define.PLUGIN1_TEXT = '\"Value was provided at build time\"';\n },\n};\n\nmodule.exports = plugin1;\n```\n\n```ts {% fileName=\"apps/my-app/plugins/plugin2.js\" %}\nfunction plugin2({ someOption }) {\n return {\n name: 'plugin2',\n setup(build) {\n const options = build.initialOptions;\n options.define.PLUGIN2_TEXT = JSON.stringify(someOption);\n },\n };\n}\n\nmodule.exports = plugin2;\n```\n\nAdditionally, we need to inform TypeScript of the defined variables to prevent type-checking errors during the build. We can achieve this by creating or updating a type definition file included in the TypeScript build process (e.g. `src/types.d.ts`) with the following content:\n\n```ts {% fileName=\"apps/my-app/src/types.d.ts\" %}\ndeclare const PLUGIN1_TEXT: number;\ndeclare const PLUGIN2_TEXT: string;\n```\n\n{% /tab %}\n\n{% tab label=\"Transforming the 'index.html' file\" %}\n\nThe executor accepts an `indexHtmlTransformer` option to provide a path to a file with a default export for a function that receives the application's `index.html` file contents and outputs the updated contents.\n\n```json {% fileName=\"apps/my-app/project.json\" highlightLines=[8] %}\n{\n ...\n \"targets\": {\n \"build\": {\n \"executor\": \"@nx/angular:application\",\n \"options\": {\n ...\n \"indexHtmlTransformer\": \"apps/my-app/index-html.transformer.ts\"\n }\n }\n ...\n }\n}\n```\n\n```ts {% fileName=\"apps/my-app/index-html.transformer.ts\" %}\nexport default function (indexContent: string) {\n return indexContent.replace(\n 'my-app',\n 'my-app (transformed)'\n );\n}\n```\n\n{% /tab %}\n{% /tabs %}\n", + "description": "Builds an Angular application using [esbuild](https://esbuild.github.io/) with integrated SSR and prerendering capabilities. _Note: this is only supported in Angular versions >= 17.0.0_.", + "examplesFile": "This executor is a drop-in replacement for 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- Providing a function to transform the application's `index.html` file\n- Incremental builds\n\n{% callout type=\"check\" title=\"Dev Server\" %}\nThe [`@nx/angular:dev-server` executor](https://nx.dev/nx-api/angular/executors/dev-server) is required to serve your application when using the `@nx/angular:application` to build it. It is a drop-in replacement for the Angular CLI's `@angular-devkit/build-angular:dev-server` builder and ensures the application is correctly served with Vite when using the `@nx/angular:application` executor.\n{% /callout %}\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 {% fileName=\"apps/my-app/project.json\" highlightLines=[\"8-16\"] %}\n{\n ...\n \"targets\": {\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\": \"some value\"\n }\n }\n ]\n }\n }\n ...\n }\n}\n```\n\n```ts {% fileName=\"apps/my-app/plugins/plugin1.js\" %}\nconst plugin1 = {\n name: 'plugin1',\n setup(build) {\n const options = build.initialOptions;\n options.define.PLUGIN1_TEXT = '\"Value was provided at build time\"';\n },\n};\n\nmodule.exports = plugin1;\n```\n\n```ts {% fileName=\"apps/my-app/plugins/plugin2.js\" %}\nfunction plugin2({ someOption }) {\n return {\n name: 'plugin2',\n setup(build) {\n const options = build.initialOptions;\n options.define.PLUGIN2_TEXT = JSON.stringify(someOption);\n },\n };\n}\n\nmodule.exports = plugin2;\n```\n\nAdditionally, we need to inform TypeScript of the defined variables to prevent type-checking errors during the build. We can achieve this by creating or updating a type definition file included in the TypeScript build process (e.g. `src/types.d.ts`) with the following content:\n\n```ts {% fileName=\"apps/my-app/src/types.d.ts\" %}\ndeclare const PLUGIN1_TEXT: number;\ndeclare const PLUGIN2_TEXT: string;\n```\n\n{% /tab %}\n\n{% tab label=\"Transforming the 'index.html' file\" %}\n\nThe executor accepts an `indexHtmlTransformer` option to provide a path to a file with a default export for a function that receives the application's `index.html` file contents and outputs the updated contents.\n\n```json {% fileName=\"apps/my-app/project.json\" highlightLines=[8] %}\n{\n ...\n \"targets\": {\n \"build\": {\n \"executor\": \"@nx/angular:application\",\n \"options\": {\n ...\n \"indexHtmlTransformer\": \"apps/my-app/index-html.transformer.ts\"\n }\n }\n ...\n }\n}\n```\n\n```ts {% fileName=\"apps/my-app/index-html.transformer.ts\" %}\nexport default function (indexContent: string) {\n return indexContent.replace(\n 'my-app',\n 'my-app (transformed)'\n );\n}\n```\n\n{% /tab %}\n{% /tabs %}\n", "outputCapture": "direct-nodejs", "type": "object", "properties": { @@ -739,7 +739,7 @@ }, "presets": [] }, - "description": "Builds an application with esbuild with support for incremental builds. _Note: this is only supported in Angular versions >= 17.0.0_.", + "description": "Builds an Angular application using [esbuild](https://esbuild.github.io/) with integrated SSR and prerendering capabilities. _Note: this is only supported in Angular versions >= 17.0.0_.", "aliases": [], "hidden": false, "path": "/packages/angular/src/executors/application/schema.json", diff --git a/docs/generated/packages/angular/executors/browser-esbuild.json b/docs/generated/packages/angular/executors/browser-esbuild.json index a0ba8fa77a..a5d920682f 100644 --- a/docs/generated/packages/angular/executors/browser-esbuild.json +++ b/docs/generated/packages/angular/executors/browser-esbuild.json @@ -4,8 +4,8 @@ "schema": { "$schema": "http://json-schema.org/draft-07/schema", "title": "Schema for Nx ESBuild Executor", - "description": "Nx ESBuild Executor supporting Incremental Builds.", - "examplesFile": "The `@nx/angular:browser-esbuild` executor is very similar to the `@angular-devkit/build-angular:browser-esbuild` builder provided by the Angular CLI. It builds an Angular application using [esbuild](https://esbuild.github.io/).\n\nIn addition to the features provided by the Angular CLI builder, the `@nx/angular:browser-esbuild` 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 {% fileName=\"apps/my-app/project.json\" highlightLines=[\"8-16\"] %}\n{\n ...\n \"targets\": {\n \"build\": {\n \"executor\": \"@nx/angular:browser-esbuild\",\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\": \"some value\"\n }\n }\n ]\n }\n }\n ...\n }\n}\n```\n\n```ts {% fileName=\"apps/my-app/plugins/plugin1.js\" %}\nconst plugin1 = {\n name: 'plugin1',\n setup(build) {\n const options = build.initialOptions;\n options.define.PLUGIN1_TEXT = '\"Value was provided at build time\"';\n },\n};\n\nmodule.exports = plugin1;\n```\n\n```ts {% fileName=\"apps/my-app/plugins/plugin2.js\" %}\nfunction plugin2({ someOption }) {\n return {\n name: 'plugin2',\n setup(build) {\n const options = build.initialOptions;\n options.define.PLUGIN2_TEXT = JSON.stringify(someOption);\n },\n };\n}\n\nmodule.exports = plugin2;\n```\n\nAdditionally, we need to inform TypeScript of the defined variables to prevent type-checking errors during the build. We can achieve this by creating or updating a type definition file included in the TypeScript build process (e.g. `src/types.d.ts`) with the following content:\n\n```ts {% fileName=\"apps/my-app/src/types.d.ts\" %}\ndeclare const PLUGIN1_TEXT: number;\ndeclare const PLUGIN2_TEXT: string;\n```\n\n{% /tab %}\n{% /tabs %}\n", + "description": "Builds an Angular application using [esbuild](https://esbuild.github.io/).", + "examplesFile": "This executor is a drop-in replacement for the `@angular-devkit/build-angular:browser-esbuild` builder provided by the Angular CLI. It builds an Angular application using esbuild.\n\nIn addition to the features provided by the Angular CLI builder, the `@nx/angular:browser-esbuild` executor also supports the following:\n\n- Providing esbuild plugins\n- Incremental builds\n\n{% callout type=\"check\" title=\"Dev Server\" %}\nThe [`@nx/angular:dev-server` executor](https://nx.dev/nx-api/angular/executors/dev-server) is required to serve your application when using the `@nx/angular:browser-esbuild` to build it. It is a drop-in replacement for the Angular CLI's `@angular-devkit/build-angular:dev-server` builder and ensures the application is correctly served with Vite when using the `@nx/angular:browser-esbuild` executor.\n{% /callout %}\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 {% fileName=\"apps/my-app/project.json\" highlightLines=[\"8-16\"] %}\n{\n ...\n \"targets\": {\n \"build\": {\n \"executor\": \"@nx/angular:browser-esbuild\",\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\": \"some value\"\n }\n }\n ]\n }\n }\n ...\n }\n}\n```\n\n```ts {% fileName=\"apps/my-app/plugins/plugin1.js\" %}\nconst plugin1 = {\n name: 'plugin1',\n setup(build) {\n const options = build.initialOptions;\n options.define.PLUGIN1_TEXT = '\"Value was provided at build time\"';\n },\n};\n\nmodule.exports = plugin1;\n```\n\n```ts {% fileName=\"apps/my-app/plugins/plugin2.js\" %}\nfunction plugin2({ someOption }) {\n return {\n name: 'plugin2',\n setup(build) {\n const options = build.initialOptions;\n options.define.PLUGIN2_TEXT = JSON.stringify(someOption);\n },\n };\n}\n\nmodule.exports = plugin2;\n```\n\nAdditionally, we need to inform TypeScript of the defined variables to prevent type-checking errors during the build. We can achieve this by creating or updating a type definition file included in the TypeScript build process (e.g. `src/types.d.ts`) with the following content:\n\n```ts {% fileName=\"apps/my-app/src/types.d.ts\" %}\ndeclare const PLUGIN1_TEXT: number;\ndeclare const PLUGIN2_TEXT: string;\n```\n\n{% /tab %}\n{% /tabs %}\n", "outputCapture": "direct-nodejs", "type": "object", "properties": { @@ -648,7 +648,7 @@ }, "presets": [] }, - "description": "Builds your application with esbuild and adds support for incremental builds.", + "description": "Builds an Angular application using [esbuild](https://esbuild.github.io/).", "aliases": [], "hidden": false, "path": "/packages/angular/src/executors/browser-esbuild/schema.json", diff --git a/docs/generated/packages/angular/executors/dev-server.json b/docs/generated/packages/angular/executors/dev-server.json index 57e71c318f..21fba1e633 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": "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", + "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](https://esbuild.github.io/)-based executor.", + "examplesFile": "This executor is a drop-in replacement for 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- Serving applications with Vite when using the `@nx/angular:application` or `@nx/angular:browser-esbuild` executors to build them\n- Serving applications with webpack when using the `@nx/angular:webpack-browser` executor\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"] } @@ -148,7 +148,7 @@ { "required": ["browserTarget"] } ] }, - "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.", + "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](https://esbuild.github.io/)-based executor.", "aliases": [], "hidden": false, "path": "/packages/angular/src/builders/dev-server/schema.json", diff --git a/docs/generated/packages/angular/executors/module-federation-dev-server.json b/docs/generated/packages/angular/executors/module-federation-dev-server.json index 2023860648..20bfd91d6b 100644 --- a/docs/generated/packages/angular/executors/module-federation-dev-server.json +++ b/docs/generated/packages/angular/executors/module-federation-dev-server.json @@ -5,7 +5,7 @@ "$schema": "http://json-schema.org/draft-07/schema", "title": "Schema for Module Federation Dev Server", "outputCapture": "direct-nodejs", - "description": "The module-federation-dev-server executor is reserved exclusively for use with host Module Federation applications. It allows the user to specify which remote applications should be served with the host.", + "description": "Serves host [Module Federation](https://module-federation.io/) applications ([webpack](https://webpack.js.org/)-based) allowing to specify which remote applications should be served with the host.", "type": "object", "presets": [ { "name": "Using a Different Port", "keys": ["buildTarget", "port"] } @@ -149,7 +149,7 @@ ], "examplesFile": "## Examples\n\n{% tabs %}\n\n{% tab label=\"Basic Usage\" %}\nThe Module Federation Dev Server will serve a host application and find the remote applications associated with the host and serve them statically also. \nSee an example set up of it below:\n\n```json\n{\n \"serve\": {\n \"executor\": \"@nx/angular:module-federation-dev-server\",\n \"configurations\": {\n \"production\": {\n \"buildTarget\": \"host:build:production\"\n },\n \"development\": {\n \"buildTarget\": \"host:build:development\"\n }\n },\n \"defaultConfiguration\": \"development\",\n \"options\": {\n \"port\": 4200,\n \"publicHost\": \"http://localhost:4200\"\n }\n }\n}\n```\n\n{% /tab %}\n\n{% tab label=\"Serve host with remotes that can be live reloaded\" %}\nThe Module Federation Dev Server will serve a host application and find the remote applications associated with the host and serve a set selection with live reloading enabled also. \nSee an example set up of it below:\n\n```json\n{\n \"serve-with-hmr-remotes\": {\n \"executor\": \"@nx/angular:module-federation-dev-server\",\n \"configurations\": {\n \"production\": {\n \"buildTarget\": \"host:build:production\"\n },\n \"development\": {\n \"buildTarget\": \"host:build:development\"\n }\n },\n \"defaultConfiguration\": \"development\",\n \"options\": {\n \"port\": 4200,\n \"publicHost\": \"http://localhost:4200\",\n \"devRemotes\": [\"remote1\", \"remote2\"]\n }\n }\n}\n```\n\n{% /tab %}\n\n{% /tabs %}\n" }, - "description": "The module-federation-dev-server executor is reserved exclusively for use with host Module Federation applications. It allows the user to specify which remote applications should be served with the host.", + "description": "Serves host [Module Federation](https://module-federation.io/) applications ([webpack](https://webpack.js.org/)-based) allowing to specify which remote applications should be served with the host.", "aliases": [], "hidden": false, "path": "/packages/angular/src/executors/module-federation-dev-server/schema.json", diff --git a/docs/generated/packages/angular/executors/module-federation-dev-ssr.json b/docs/generated/packages/angular/executors/module-federation-dev-ssr.json index 28330f038d..53aebbfba5 100644 --- a/docs/generated/packages/angular/executors/module-federation-dev-ssr.json +++ b/docs/generated/packages/angular/executors/module-federation-dev-ssr.json @@ -4,7 +4,7 @@ "schema": { "$schema": "http://json-schema.org/draft-07/schema", "title": "Module Federation SSR Dev Server Target", - "description": "SSR Dev Server target options for Module Federation host applications.", + "description": "Serves host [Module Federation](https://module-federation.io/) applications ([webpack](https://webpack.js.org/)-based) that use SSR allowing to specify which remote applications should be served with the host.", "type": "object", "properties": { "browserTarget": { @@ -88,7 +88,7 @@ "required": ["browserTarget", "serverTarget"], "presets": [] }, - "description": "The module-federation-dev-ssr executor is reserved exclusively for use with host Module Federation applications that use SSR. It allows the user to specify which remote applications should be served with the host.", + "description": "Serves host [Module Federation](https://module-federation.io/) applications ([webpack](https://webpack.js.org/)-based) that use SSR allowing to specify which remote applications should be served with the host.", "aliases": [], "hidden": false, "path": "/packages/angular/src/builders/module-federation-dev-ssr/schema.json", diff --git a/docs/generated/packages/angular/executors/ng-packagr-lite.json b/docs/generated/packages/angular/executors/ng-packagr-lite.json index c449cab349..048e94ac6a 100644 --- a/docs/generated/packages/angular/executors/ng-packagr-lite.json +++ b/docs/generated/packages/angular/executors/ng-packagr-lite.json @@ -6,7 +6,7 @@ "outputCapture": "direct-nodejs", "$schema": "https://json-schema.org/schema", "title": "ng-packagr Target", - "description": "Builds a library with support for incremental builds.\n\nThis executor is meant to be used with buildable libraries in an incremental build scenario. It is similar to the `@nx/angular:package` executor but with some key differences:\n- For supported Angular versions lower than v16, it doesn't run `ngcc` automatically (`ngcc` is no longer available from Angular v16 onwards, for lower versions, it needs to be run separately beforehand if needed, this can be done in a `postinstall` hook on `package.json`).\n- It only produces ESM2022 bundles (ESM2020 for supported Angular versions lower than v16).", + "description": "Builds an Angular library with support for incremental builds.\n\nThis executor is meant to be used with buildable libraries in an incremental build scenario. It is similar to the `@nx/angular:package` executor but with some key differences:\n- For supported Angular versions lower than v16, it doesn't run `ngcc` automatically (`ngcc` is no longer available from Angular v16 onwards, for lower versions, it needs to be run separately beforehand if needed, this can be done in a `postinstall` hook on `package.json`).\n- It only produces ESM2022 bundles (ESM2020 for supported Angular versions lower than v16).", "cli": "nx", "type": "object", "presets": [ @@ -44,7 +44,7 @@ "additionalProperties": false, "required": ["project"] }, - "description": "Builds a library with support for incremental builds.\nThis executor is meant to be used with buildable libraries in an incremental build scenario. It is similar to the `@nrwl/angular:package` executor but with some key differences:\n- It doesn't run `ngcc` automatically (`ngcc` needs to be run separately beforehand if needed, this can be done in a `postinstall` hook on `package.json`).\n- It only produces ESM2020 bundles.\n- It doesn't generate package exports in the `package.json`.", + "description": "Builds an Angular library with support for incremental builds.\n\nThis executor is meant to be used with buildable libraries in an incremental build scenario. It is similar to the `@nx/angular:package` executor but with some key differences:\n- For supported Angular versions lower than v16, it doesn't run `ngcc` automatically (`ngcc` is no longer available from Angular v16 onwards, for lower versions, it needs to be run separately beforehand if needed, this can be done in a `postinstall` hook on `package.json`).\n- It only produces ESM2022 bundles (ESM2020 for supported Angular versions lower than v16).", "aliases": [], "hidden": false, "path": "/packages/angular/src/executors/ng-packagr-lite/schema.json", diff --git a/docs/generated/packages/angular/executors/package.json b/docs/generated/packages/angular/executors/package.json index ec1861b1f4..d09a22ca14 100644 --- a/docs/generated/packages/angular/executors/package.json +++ b/docs/generated/packages/angular/executors/package.json @@ -6,7 +6,7 @@ "outputCapture": "direct-nodejs", "$schema": "https://json-schema.org/schema", "title": "ng-packagr Target", - "description": "Builds and packages an Angular library producing an output following the Angular Package Format (APF) to be distributed as an NPM package.\n\nThis executor is similar to the `@angular-devkit/build-angular:ng-packagr` with additional support for incremental builds.", + "description": "Builds and packages an Angular library producing an output following the Angular Package Format (APF) to be distributed as an NPM package.\n\nThis executor is a drop-in replacement for the `@angular-devkit/build-angular:ng-packagr` with additional support for incremental builds.", "cli": "nx", "type": "object", "presets": [ @@ -53,7 +53,7 @@ "project" ] }, - "description": "Builds and packages an Angular library producing an output following the Angular Package Format (APF) to be distributed as an NPM package.\nThis executor is similar to the `@angular-devkit/build-angular:ng-packagr` with additional support for incremental builds.", + "description": "Builds and packages an Angular library producing an output following the Angular Package Format (APF) to be distributed as an NPM package.\n\nThis executor is a drop-in replacement for the `@angular-devkit/build-angular:ng-packagr` with additional support for incremental builds.", "aliases": [], "hidden": false, "path": "/packages/angular/src/executors/package/schema.json", diff --git a/docs/generated/packages/angular/executors/webpack-browser.json b/docs/generated/packages/angular/executors/webpack-browser.json index ab45f3e1f9..7bac4ebe54 100644 --- a/docs/generated/packages/angular/executors/webpack-browser.json +++ b/docs/generated/packages/angular/executors/webpack-browser.json @@ -6,8 +6,8 @@ "outputCapture": "direct-nodejs", "$schema": "http://json-schema.org/draft-07/schema", "title": "Schema for Webpack Browser", - "description": "The webpack-browser executor is very similar to the standard browser builder provided by the Angular Devkit. It allows you to build your Angular application to a build artifact that can be hosted online. There are some key differences: \n- Supports Custom Webpack Configurations \n- Supports Incremental Building", - "examplesFile": "##### Using a custom webpack configuration\n\nThe executor supports providing a path to a custom webpack configuration. This allows you to customize how your Angular application is built. It currently supports the following types of webpack configurations:\n\n- `object`\n- `Function`\n- `Promise`\n\nThe executor will merge the provided configuration with the webpack configuration that Angular Devkit uses. The merge order is:\n\n- Angular Devkit Configuration\n- Provided Configuration\n\nTo use a custom webpack configuration when building your Angular application, change the `build` target in your `project.json` to match the following:\n\n```typescript\n\"build\": {\n \"executor\": \"@nx/angular:webpack-browser\",\n \"options\": {\n ...\n \"customWebpackConfig\": {\n \"path\": \"apps/appName/webpack.config.js\"\n }\n }\n}\n```\n\n##### Incrementally Building your Application\n\nThe executor supports incrementally building your Angular application by building the workspace libraries it depends on _(that have been marked as buildable)_ and then building your application using the built source of the libraries.\n\nThis can improve build time as the building of the workspace libraries can be cached, meaning they only have to be rebuilt if they have changed.\n\n> Note: There may be some additional overhead in the linking of the built libraries' sources which may reduce the overall improvement in build time. Therefore this approach only benefits large applications and would likely have a negative impact on small and medium applications.\n\nTo allow your Angular application to take advantage of incremental building, change the `build` target in your `project.json` to match the following:\n\n```typescript\n\"build\": {\n \"executor\": \"@nx/angular:webpack-browser\",\n \"options\": {\n ...\n \"buildLibsFromSource\": false\n }\n}\n```\n", + "description": "Builds an Angular application using [webpack](https://webpack.js.org/).", + "examplesFile": "This executor is a drop-in replacement for the `@angular-devkit/build-angular:browser` builder provided by the Angular CLI. It builds an Angular application using [webpack](https://webpack.js.org/).\n\nIn addition to the features provided by the Angular CLI builder, the `@nx/angular:webpack-browser` executor also supports the following:\n\n- Providing a custom webpack configuration\n- Incremental builds\n\n{% callout type=\"check\" title=\"Dev Server\" %}\nThe [`@nx/angular:dev-server` executor](https://nx.dev/nx-api/angular/executors/dev-server) is required to serve your application when using the `@nx/angular:browser-esbuild` to build it. It is a drop-in replacement for the Angular CLI's `@angular-devkit/build-angular:dev-server` builder and ensures the application is correctly served with Vite when using the `@nx/angular:browser-esbuild` executor.\n{% /callout %}\n\n## Examples\n\n{% tabs %}\n{% tab label=\"Using a custom webpack configuration\" %}\n\nThe executor supports providing a path to a custom webpack configuration. This allows you to customize how your Angular application is built. It currently supports the following types of webpack configurations:\n\n- `object`\n- `Function`\n- `Promise`\n\nThe executor will merge the provided configuration with the webpack configuration that Angular Devkit uses. The merge order is:\n\n- Angular Devkit Configuration\n- Provided Configuration\n\nTo use a custom webpack configuration when building your Angular application, change the `build` target in your `project.json` to match the following:\n\n```json {% fileName=\"project.json\" highlightLines=[5,\"8-10\"] %}\n{\n ...\n \"targets\": {\n \"build\": {\n \"executor\": \"@nx/angular:webpack-browser\",\n \"options\": {\n ...\n \"customWebpackConfig\": {\n \"path\": \"apps/appName/webpack.config.js\"\n }\n }\n },\n ...\n }\n}\n```\n\n{% /tab %}\n\n{% tab label=\"Incrementally Building your Application\" %}\n\nThe executor supports incrementally building your Angular application by building the workspace libraries it depends on _(that have been marked as buildable)_ and then building your application using the built source of the libraries.\n\nThis can improve build time as the building of the workspace libraries can be cached, meaning they only have to be rebuilt if they have changed.\n\n{% callout type=\"note\" title=\"Performance\" %}\nThere may be some additional overhead in the linking of the built libraries' sources which may reduce the overall improvement in build time. Therefore this approach only benefits large applications and would likely have a negative impact on small and medium applications.\n{% /callout %}\n\nTo allow your Angular application to take advantage of incremental building, change the `build` target in your `project.json` to match the following:\n\n```json {% fileName=\"project.json\" highlightLines=[5,8] %}\n{\n ...\n \"targets\": {\n \"build\": {\n \"executor\": \"@nx/angular:webpack-browser\",\n \"options\": {\n ...\n \"buildLibsFromSource\": false\n }\n },\n ...\n }\n}\n```\n\n{% /tab %}\n{% /tabs %}\n", "type": "object", "presets": [ { @@ -689,7 +689,7 @@ } } }, - "description": "The `webpack-browser` executor is very similar to the standard `browser` builder provided by the Angular Devkit. It allows you to build your Angular application to a build artifact that can be hosted online. There are some key differences: \n- Supports Custom Webpack Configurations \n- Supports Incremental Building", + "description": "Builds an Angular application using [webpack](https://webpack.js.org/).", "aliases": [], "hidden": false, "path": "/packages/angular/src/builders/webpack-browser/schema.json", diff --git a/docs/generated/packages/angular/executors/webpack-server.json b/docs/generated/packages/angular/executors/webpack-server.json index 74bd19e9e4..e42ed8a3c0 100644 --- a/docs/generated/packages/angular/executors/webpack-server.json +++ b/docs/generated/packages/angular/executors/webpack-server.json @@ -6,7 +6,7 @@ "outputCapture": "direct-nodejs", "$schema": "http://json-schema.org/draft-07/schema", "title": "Schema for Webpack Server", - "description": "The webpack-server executor is very similar to the standard 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 and NgUniversal for SSR.", + "description": "Builds a server Angular application using [webpack](https://webpack.js.org/). This executor is a drop-in replacement for the `@angular-devkit/build-angular:server` builder provided by the Angular CLI. It is usually used in tandem with the `@nx/angular:webpack-browser` executor when your Angular application uses a custom webpack configuration.", "type": "object", "properties": { "assets": { @@ -369,7 +369,7 @@ }, "presets": [] }, - "description": "The `webpack-server` executor is very similar to the standard `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 and NgUniversal for SSR.", + "description": "Builds a server Angular application using [webpack](https://webpack.js.org/). This executor is a drop-in replacement for the `@angular-devkit/build-angular:server` builder provided by the Angular CLI. It is usually used in tandem with the `@nx/angular:webpack-browser` executor when your Angular application uses a custom webpack configuration.", "aliases": [], "hidden": false, "path": "/packages/angular/src/builders/webpack-server/schema.json", diff --git a/packages/angular/docs/application-executor-examples.md b/packages/angular/docs/application-executor-examples.md index d38c71597a..31fd1f641f 100644 --- a/packages/angular/docs/application-executor-examples.md +++ b/packages/angular/docs/application-executor-examples.md @@ -1,4 +1,4 @@ -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. +This executor is a drop-in replacement for 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. In addition to the features provided by the Angular CLI builder, the `@nx/angular:application` executor also supports the following: @@ -6,6 +6,10 @@ In addition to the features provided by the Angular CLI builder, the `@nx/angula - Providing a function to transform the application's `index.html` file - Incremental builds +{% callout type="check" title="Dev Server" %} +The [`@nx/angular:dev-server` executor](https://nx.dev/nx-api/angular/executors/dev-server) is required to serve your application when using the `@nx/angular:application` to build it. It is a drop-in replacement for the Angular CLI's `@angular-devkit/build-angular:dev-server` builder and ensures the application is correctly served with Vite when using the `@nx/angular:application` executor. +{% /callout %} + ## Examples {% tabs %} diff --git a/packages/angular/docs/browser-esbuild-examples.md b/packages/angular/docs/browser-esbuild-examples.md index b27b814db5..527acf62fe 100644 --- a/packages/angular/docs/browser-esbuild-examples.md +++ b/packages/angular/docs/browser-esbuild-examples.md @@ -1,10 +1,14 @@ -The `@nx/angular:browser-esbuild` executor is very similar to the `@angular-devkit/build-angular:browser-esbuild` builder provided by the Angular CLI. It builds an Angular application using [esbuild](https://esbuild.github.io/). +This executor is a drop-in replacement for the `@angular-devkit/build-angular:browser-esbuild` builder provided by the Angular CLI. It builds an Angular application using esbuild. In addition to the features provided by the Angular CLI builder, the `@nx/angular:browser-esbuild` executor also supports the following: - Providing esbuild plugins - Incremental builds +{% callout type="check" title="Dev Server" %} +The [`@nx/angular:dev-server` executor](https://nx.dev/nx-api/angular/executors/dev-server) is required to serve your application when using the `@nx/angular:browser-esbuild` to build it. It is a drop-in replacement for the Angular CLI's `@angular-devkit/build-angular:dev-server` builder and ensures the application is correctly served with Vite when using the `@nx/angular:browser-esbuild` executor. +{% /callout %} + ## Examples {% tabs %} diff --git a/packages/angular/docs/dev-server-examples.md b/packages/angular/docs/dev-server-examples.md index fa51f375a2..589b676490 100644 --- a/packages/angular/docs/dev-server-examples.md +++ b/packages/angular/docs/dev-server-examples.md @@ -1,15 +1,16 @@ -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 is a drop-in replacement for 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: -- Best integration for `@nx/angular:webpack-browser`, `@nx/angular:browser-esbuild` and `@nx/angular:application` +- Serving applications with Vite when using the `@nx/angular:application` or `@nx/angular:browser-esbuild` executors to build them +- Serving applications with webpack when using the `@nx/angular:webpack-browser` executor - Providing HTTP request middleware functions when the build target is using an esbuild-based executor - Incremental builds ## Examples {% tabs %} -{% tab label="Using a custom Webpack configuration" %} +{% 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. +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: diff --git a/packages/angular/docs/webpack-browser-examples.md b/packages/angular/docs/webpack-browser-examples.md index f6c9f611a8..a6b78b047b 100644 --- a/packages/angular/docs/webpack-browser-examples.md +++ b/packages/angular/docs/webpack-browser-examples.md @@ -1,4 +1,18 @@ -##### Using a custom webpack configuration +This executor is a drop-in replacement for the `@angular-devkit/build-angular:browser` builder provided by the Angular CLI. It builds an Angular application using [webpack](https://webpack.js.org/). + +In addition to the features provided by the Angular CLI builder, the `@nx/angular:webpack-browser` executor also supports the following: + +- Providing a custom webpack configuration +- Incremental builds + +{% callout type="check" title="Dev Server" %} +The [`@nx/angular:dev-server` executor](https://nx.dev/nx-api/angular/executors/dev-server) is required to serve your application when using the `@nx/angular:browser-esbuild` to build it. It is a drop-in replacement for the Angular CLI's `@angular-devkit/build-angular:dev-server` builder and ensures the application is correctly served with Vite when using the `@nx/angular:browser-esbuild` executor. +{% /callout %} + +## Examples + +{% tabs %} +{% tab label="Using a custom webpack configuration" %} The executor supports providing a path to a custom webpack configuration. This allows you to customize how your Angular application is built. It currently supports the following types of webpack configurations: @@ -13,34 +27,53 @@ The executor will merge the provided configuration with the webpack configuratio To use a custom webpack configuration when building your Angular application, change the `build` target in your `project.json` to match the following: -```typescript -"build": { - "executor": "@nx/angular:webpack-browser", - "options": { +```json {% fileName="project.json" highlightLines=[5,"8-10"] %} +{ + ... + "targets": { + "build": { + "executor": "@nx/angular:webpack-browser", + "options": { + ... + "customWebpackConfig": { + "path": "apps/appName/webpack.config.js" + } + } + }, ... - "customWebpackConfig": { - "path": "apps/appName/webpack.config.js" - } } } ``` -##### Incrementally Building your Application +{% /tab %} + +{% tab label="Incrementally Building your Application" %} The executor supports incrementally building your Angular application by building the workspace libraries it depends on _(that have been marked as buildable)_ and then building your application using the built source of the libraries. This can improve build time as the building of the workspace libraries can be cached, meaning they only have to be rebuilt if they have changed. -> Note: There may be some additional overhead in the linking of the built libraries' sources which may reduce the overall improvement in build time. Therefore this approach only benefits large applications and would likely have a negative impact on small and medium applications. +{% callout type="note" title="Performance" %} +There may be some additional overhead in the linking of the built libraries' sources which may reduce the overall improvement in build time. Therefore this approach only benefits large applications and would likely have a negative impact on small and medium applications. +{% /callout %} To allow your Angular application to take advantage of incremental building, change the `build` target in your `project.json` to match the following: -```typescript -"build": { - "executor": "@nx/angular:webpack-browser", - "options": { +```json {% fileName="project.json" highlightLines=[5,8] %} +{ + ... + "targets": { + "build": { + "executor": "@nx/angular:webpack-browser", + "options": { + ... + "buildLibsFromSource": false + } + }, ... - "buildLibsFromSource": false } } ``` + +{% /tab %} +{% /tabs %} diff --git a/packages/angular/executors.json b/packages/angular/executors.json index 592c8960db..7d0df96c13 100644 --- a/packages/angular/executors.json +++ b/packages/angular/executors.json @@ -8,27 +8,27 @@ "ng-packagr-lite": { "implementation": "./src/executors/ng-packagr-lite/ng-packagr-lite.impl", "schema": "./src/executors/ng-packagr-lite/schema.json", - "description": "Builds a library with support for incremental builds.\nThis executor is meant to be used with buildable libraries in an incremental build scenario. It is similar to the `@nrwl/angular:package` executor but with some key differences:\n- It doesn't run `ngcc` automatically (`ngcc` needs to be run separately beforehand if needed, this can be done in a `postinstall` hook on `package.json`).\n- It only produces ESM2020 bundles.\n- It doesn't generate package exports in the `package.json`." + "description": "Builds an Angular library with support for incremental builds.\n\nThis executor is meant to be used with buildable libraries in an incremental build scenario. It is similar to the `@nx/angular:package` executor but with some key differences:\n- For supported Angular versions lower than v16, it doesn't run `ngcc` automatically (`ngcc` is no longer available from Angular v16 onwards, for lower versions, it needs to be run separately beforehand if needed, this can be done in a `postinstall` hook on `package.json`).\n- It only produces ESM2022 bundles (ESM2020 for supported Angular versions lower than v16)." }, "package": { "implementation": "./src/executors/package/package.impl", "schema": "./src/executors/package/schema.json", - "description": "Builds and packages an Angular library producing an output following the Angular Package Format (APF) to be distributed as an NPM package.\nThis executor is similar to the `@angular-devkit/build-angular:ng-packagr` with additional support for incremental builds." + "description": "Builds and packages an Angular library producing an output following the Angular Package Format (APF) to be distributed as an NPM package.\n\nThis executor is a drop-in replacement for the `@angular-devkit/build-angular:ng-packagr` with additional support for incremental builds." }, "browser-esbuild": { "implementation": "./src/executors/browser-esbuild/browser-esbuild.impl", "schema": "./src/executors/browser-esbuild/schema.json", - "description": "Builds your application with esbuild and adds support for incremental builds." + "description": "Builds an Angular application using [esbuild](https://esbuild.github.io/)." }, "module-federation-dev-server": { "implementation": "./src/executors/module-federation-dev-server/module-federation-dev-server.impl", "schema": "./src/executors/module-federation-dev-server/schema.json", - "description": "The module-federation-dev-server executor is reserved exclusively for use with host Module Federation applications. It allows the user to specify which remote applications should be served with the host." + "description": "Serves host [Module Federation](https://module-federation.io/) applications ([webpack](https://webpack.js.org/)-based) allowing to specify which remote applications should be served with the host." }, "application": { "implementation": "./src/executors/application/application.impl", "schema": "./src/executors/application/schema.json", - "description": "Builds an application with esbuild with support for incremental builds. _Note: this is only supported in Angular versions >= 17.0.0_." + "description": "Builds an Angular application using [esbuild](https://esbuild.github.io/) with integrated SSR and prerendering capabilities. _Note: this is only supported in Angular versions >= 17.0.0_." }, "extract-i18n": { "implementation": "./src/executors/extract-i18n/extract-i18n.impl", @@ -40,22 +40,22 @@ "webpack-browser": { "implementation": "./src/builders/webpack-browser/webpack-browser.impl", "schema": "./src/builders/webpack-browser/schema.json", - "description": "The `webpack-browser` executor is very similar to the standard `browser` builder provided by the Angular Devkit. It allows you to build your Angular application to a build artifact that can be hosted online. There are some key differences: \n- Supports Custom Webpack Configurations \n- Supports Incremental Building" + "description": "Builds an Angular application using [webpack](https://webpack.js.org/)." }, "dev-server": { "implementation": "./src/builders/dev-server/dev-server.impl", "schema": "./src/builders/dev-server/schema.json", - "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." + "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](https://esbuild.github.io/)-based executor." }, "webpack-server": { "implementation": "./src/builders/webpack-server/webpack-server.impl", "schema": "./src/builders/webpack-server/schema.json", - "description": "The `webpack-server` executor is very similar to the standard `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 and NgUniversal for SSR." + "description": "Builds a server Angular application using [webpack](https://webpack.js.org/). This executor is a drop-in replacement for the `@angular-devkit/build-angular:server` builder provided by the Angular CLI. It is usually used in tandem with the `@nx/angular:webpack-browser` executor when your Angular application uses a custom webpack configuration." }, "module-federation-dev-ssr": { "implementation": "./src/builders/module-federation-dev-ssr/module-federation-dev-ssr.impl", "schema": "./src/builders/module-federation-dev-ssr/schema.json", - "description": "The module-federation-dev-ssr executor is reserved exclusively for use with host Module Federation applications that use SSR. It allows the user to specify which remote applications should be served with the host." + "description": "Serves host [Module Federation](https://module-federation.io/) applications ([webpack](https://webpack.js.org/)-based) that use SSR allowing to specify which remote applications should be served with the host." } } } diff --git a/packages/angular/src/builders/dev-server/schema.json b/packages/angular/src/builders/dev-server/schema.json index e92d3c6ca9..a7244b7bd4 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": "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.", + "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](https://esbuild.github.io/)-based executor.", "examplesFile": "../../../docs/dev-server-examples.md", "type": "object", "presets": [ diff --git a/packages/angular/src/builders/module-federation-dev-ssr/schema.json b/packages/angular/src/builders/module-federation-dev-ssr/schema.json index 31dd2e589b..7f35f61cbb 100644 --- a/packages/angular/src/builders/module-federation-dev-ssr/schema.json +++ b/packages/angular/src/builders/module-federation-dev-ssr/schema.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-07/schema", "title": "Module Federation SSR Dev Server Target", - "description": "SSR Dev Server target options for Module Federation host applications.", + "description": "Serves host [Module Federation](https://module-federation.io/) applications ([webpack](https://webpack.js.org/)-based) that use SSR allowing to specify which remote applications should be served with the host.", "type": "object", "properties": { "browserTarget": { diff --git a/packages/angular/src/builders/webpack-browser/schema.json b/packages/angular/src/builders/webpack-browser/schema.json index 8d75290654..9a91136502 100644 --- a/packages/angular/src/builders/webpack-browser/schema.json +++ b/packages/angular/src/builders/webpack-browser/schema.json @@ -3,7 +3,7 @@ "outputCapture": "direct-nodejs", "$schema": "http://json-schema.org/draft-07/schema", "title": "Schema for Webpack Browser", - "description": "The webpack-browser executor is very similar to the standard browser builder provided by the Angular Devkit. It allows you to build your Angular application to a build artifact that can be hosted online. There are some key differences: \n- Supports Custom Webpack Configurations \n- Supports Incremental Building", + "description": "Builds an Angular application using [webpack](https://webpack.js.org/).", "examplesFile": "../../../docs/webpack-browser-examples.md", "type": "object", "presets": [ diff --git a/packages/angular/src/builders/webpack-server/schema.json b/packages/angular/src/builders/webpack-server/schema.json index ea46036c46..1aced7b196 100644 --- a/packages/angular/src/builders/webpack-server/schema.json +++ b/packages/angular/src/builders/webpack-server/schema.json @@ -3,7 +3,7 @@ "outputCapture": "direct-nodejs", "$schema": "http://json-schema.org/draft-07/schema", "title": "Schema for Webpack Server", - "description": "The webpack-server executor is very similar to the standard 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 and NgUniversal for SSR.", + "description": "Builds a server Angular application using [webpack](https://webpack.js.org/). This executor is a drop-in replacement for the `@angular-devkit/build-angular:server` builder provided by the Angular CLI. It is usually used in tandem with the `@nx/angular:webpack-browser` executor when your Angular application uses a custom webpack configuration.", "type": "object", "properties": { "assets": { diff --git a/packages/angular/src/executors/application/schema.json b/packages/angular/src/executors/application/schema.json index 3e901871dc..1d124fa074 100644 --- a/packages/angular/src/executors/application/schema.json +++ b/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. _Note: this is only supported in Angular versions >= 17.0.0_.", + "description": "Builds an Angular application using [esbuild](https://esbuild.github.io/) with integrated SSR and prerendering capabilities. _Note: this is only supported in Angular versions >= 17.0.0_.", "examplesFile": "../../../docs/application-executor-examples.md", "outputCapture": "direct-nodejs", "type": "object", diff --git a/packages/angular/src/executors/browser-esbuild/schema.json b/packages/angular/src/executors/browser-esbuild/schema.json index 9eed74a1ae..8bf09295d1 100644 --- a/packages/angular/src/executors/browser-esbuild/schema.json +++ b/packages/angular/src/executors/browser-esbuild/schema.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-07/schema", "title": "Schema for Nx ESBuild Executor", - "description": "Nx ESBuild Executor supporting Incremental Builds.", + "description": "Builds an Angular application using [esbuild](https://esbuild.github.io/).", "examplesFile": "../../../docs/browser-esbuild-examples.md", "outputCapture": "direct-nodejs", "type": "object", diff --git a/packages/angular/src/executors/module-federation-dev-server/schema.json b/packages/angular/src/executors/module-federation-dev-server/schema.json index 81b7b24785..ba1a8e27d8 100644 --- a/packages/angular/src/executors/module-federation-dev-server/schema.json +++ b/packages/angular/src/executors/module-federation-dev-server/schema.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema", "title": "Schema for Module Federation Dev Server", "outputCapture": "direct-nodejs", - "description": "The module-federation-dev-server executor is reserved exclusively for use with host Module Federation applications. It allows the user to specify which remote applications should be served with the host.", + "description": "Serves host [Module Federation](https://module-federation.io/) applications ([webpack](https://webpack.js.org/)-based) allowing to specify which remote applications should be served with the host.", "type": "object", "presets": [ { diff --git a/packages/angular/src/executors/ng-packagr-lite/schema.json b/packages/angular/src/executors/ng-packagr-lite/schema.json index 5161329873..703d9b7856 100644 --- a/packages/angular/src/executors/ng-packagr-lite/schema.json +++ b/packages/angular/src/executors/ng-packagr-lite/schema.json @@ -3,7 +3,7 @@ "outputCapture": "direct-nodejs", "$schema": "https://json-schema.org/schema", "title": "ng-packagr Target", - "description": "Builds a library with support for incremental builds.\n\nThis executor is meant to be used with buildable libraries in an incremental build scenario. It is similar to the `@nx/angular:package` executor but with some key differences:\n- For supported Angular versions lower than v16, it doesn't run `ngcc` automatically (`ngcc` is no longer available from Angular v16 onwards, for lower versions, it needs to be run separately beforehand if needed, this can be done in a `postinstall` hook on `package.json`).\n- It only produces ESM2022 bundles (ESM2020 for supported Angular versions lower than v16).", + "description": "Builds an Angular library with support for incremental builds.\n\nThis executor is meant to be used with buildable libraries in an incremental build scenario. It is similar to the `@nx/angular:package` executor but with some key differences:\n- For supported Angular versions lower than v16, it doesn't run `ngcc` automatically (`ngcc` is no longer available from Angular v16 onwards, for lower versions, it needs to be run separately beforehand if needed, this can be done in a `postinstall` hook on `package.json`).\n- It only produces ESM2022 bundles (ESM2020 for supported Angular versions lower than v16).", "cli": "nx", "type": "object", "presets": [ diff --git a/packages/angular/src/executors/package/schema.json b/packages/angular/src/executors/package/schema.json index c93cb01b0a..8463938533 100644 --- a/packages/angular/src/executors/package/schema.json +++ b/packages/angular/src/executors/package/schema.json @@ -3,7 +3,7 @@ "outputCapture": "direct-nodejs", "$schema": "https://json-schema.org/schema", "title": "ng-packagr Target", - "description": "Builds and packages an Angular library producing an output following the Angular Package Format (APF) to be distributed as an NPM package.\n\nThis executor is similar to the `@angular-devkit/build-angular:ng-packagr` with additional support for incremental builds.", + "description": "Builds and packages an Angular library producing an output following the Angular Package Format (APF) to be distributed as an NPM package.\n\nThis executor is a drop-in replacement for the `@angular-devkit/build-angular:ng-packagr` with additional support for incremental builds.", "cli": "nx", "type": "object", "presets": [