chore: import upstream snapshot with attribution

2026-07-13 12:38:36 +08:00
commit 8e2a6eb840
10194 changed files with 1593658 additions and 0 deletions
@@ -0,0 +1,103 @@
+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:
+
+- Providing esbuild plugins
+- Providing a function to transform the application's `index.html` file
+- Incremental builds
+
+:::tip[Dev Server]
+The [`@nx/angular:dev-server` executor](/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.
+:::
+
+## Examples
+
+##### Providing esbuild plugins
+
+The 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.
+
+```json title="apps/my-app/project.json" {8-16}
+{
+  ...
+  "targets": {
+    "build": {
+      "executor": "@nx/angular:application",
+      "options": {
+        ...
+        "plugins": [
+          "apps/my-app/plugins/plugin1.js",
+          {
+            "path": "apps/my-app/plugins/plugin2.js",
+            "options": {
+              "someOption": "some value"
+            }
+          }
+        ]
+      }
+    }
+    ...
+  }
+}
+```
+
+```ts title="apps/my-app/plugins/plugin1.js"
+const plugin1 = {
+  name: 'plugin1',
+  setup(build) {
+    const options = build.initialOptions;
+    options.define.PLUGIN1_TEXT = '"Value was provided at build time"';
+  },
+};
+
+module.exports = plugin1;
+```
+
+```ts title="apps/my-app/plugins/plugin2.js"
+function plugin2({ someOption }) {
+  return {
+    name: 'plugin2',
+    setup(build) {
+      const options = build.initialOptions;
+      options.define.PLUGIN2_TEXT = JSON.stringify(someOption);
+    },
+  };
+}
+
+module.exports = plugin2;
+```
+
+Additionally, 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:
+
+```ts title="apps/my-app/src/types.d.ts"
+declare const PLUGIN1_TEXT: number;
+declare const PLUGIN2_TEXT: string;
+```
+
+##### Transforming the 'index.html' file
+
+The 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.
+
+```json title="apps/my-app/project.json" {8}
+{
+  ...
+  "targets": {
+    "build": {
+      "executor": "@nx/angular:application",
+      "options": {
+        ...
+        "indexHtmlTransformer": "apps/my-app/index-html.transformer.ts"
+      }
+    }
+    ...
+  }
+}
+```
+
+```ts title="apps/my-app/index-html.transformer.ts"
+export default function (indexContent: string) {
+  return indexContent.replace(
+    '<title>my-app</title>',
+    '<title>my-app (transformed)</title>'
+  );
+}
+```