feat(custom-esbuild): add unit-test builder

th0r · th0r · commit 02e8d60a51fb · 2025-09-15T18:43:00.000+03:00
diff --git a/merge-schemes.ts b/merge-schemes.ts
@@ -29,5 +29,9 @@ for (const {
     (extendedSchema: any, currentExtension: any) => merge(extendedSchema, currentExtension),
     originalSchema
   );
-  writeFileSync(newSchemaPath, JSON.stringify(newSchema, null, 2), 'utf-8');
+  writeFileSync(newSchemaPath, JSON.stringify(newSchema, schemaValueReplacer, 2), 'utf-8');
+}
+
+function schemaValueReplacer(key: unknown, value: unknown) {
+  return value === '__DELETE__' ? undefined : value;
 }
diff --git a/packages/bazel/package.json b/packages/bazel/package.json
@@ -34,12 +34,12 @@
     "ci": "node ./scripts/ci.js"
   },
   "dependencies": {
-    "@angular-devkit/architect": ">=0.2000.0 < 0.2100.0",
+    "@angular-devkit/architect": ">=0.2001.0 < 0.2100.0",
     "@bazel/bazelisk": "^1.26.0",
     "@bazel/ibazel": "^0.25.0"
   },
   "devDependencies": {
-    "@angular-devkit/core": "^20.0.0",
+    "@angular-devkit/core": "^20.1.0",
     "cpy-cli": "^5.0.0",
     "quicktype": "^15.0.260",
     "rimraf": "^5.0.0",
diff --git a/packages/common/package.json b/packages/common/package.json
@@ -20,7 +20,7 @@
     "clean": "rimraf dist"
   },
   "dependencies": {
-    "@angular-devkit/core": "^20.0.0",
+    "@angular-devkit/core": "^20.1.0",
     "ts-node": "^10.0.0",
     "tsconfig-paths": "^4.2.0"
   },
diff --git a/packages/custom-esbuild/README.md b/packages/custom-esbuild/README.md
@@ -13,6 +13,8 @@ Allow customizing ESBuild configuration
     - [Example](#example)
   - [Custom ESBuild `dev-server`](#custom-esbuild-dev-server)
     - [Example](#example)
+  - [Custom ESBuild `unit-test`](#custom-esbuild-unit-test)
+    - [Example](#example-1)
 - [Index Transform](#index-transform)
   - [Example](#example-2)
 - [ES Modules (ESM) Support](#es-modules-esm-support)
@@ -46,15 +48,15 @@ Allow customizing ESBuild configuration
         "architect": {
           ...
           "[architect-target]": {
-            "builder": "@angular-builders/custom-esbuild:[application|dev-server]",
+            "builder": "@angular-builders/custom-esbuild:[application|dev-server|unit-test]",
             "options": {
               ...
             }
     ```
     Where:
     - [project] is the name of the project to which you want to add the builder
     - [architect-target] is the name of build target you want to run (build, serve, test etc. or any custom target)
-    - [application|dev-server] one of the supported builders - [application](#Custom-webpack-browser) or [dev-server](#Custom-webpack-extract-i18n)
+    - [application|dev-server|unit-test] one of the supported builders - [application](#Custom-esbuild-application), [dev-server](#Custom-esbuild-dev-server), or [unit-test](#Custom-esbuild-unit-test)
 3.  If `[architect-target]` is not one of the predefined targets (like build, serve, test etc.) then run it like this:  
     `ng run [project]:[architect-target]`  
     If it is one of the predefined targets, you can run it with `ng [architect-target]`
@@ -81,6 +83,7 @@ Allow customizing ESBuild configuration
 
 - [@angular-builders/custom-esbuild:application](#Custom-esbuild-application)
 - [@angular-builders/custom-esbuild:dev-server](#Custom-esbuild-dev-server)
+- [@angular-builders/custom-esbuild:unit-test](#Custom-esbuild-unit-test)
 
 ## Custom ESBuild `application`
 
@@ -228,6 +231,35 @@ The `@angular-builders/custom-esbuild:dev-server` is an enhanced version of the
   }
 ```
 
+## Custom ESBuild `unit-test`
+
+The `@angular-builders/custom-esbuild:unit-test` builder is an enhanced version of the `@angular/build:unit-test` builder that reuses your application ESBuild plugins during test execution. It reads the `plugins` from the referenced `:application` build target and runs the official unit test builder with those plugins applied.
+There is no need to specify a `runner` option as the only supported test runner is Vitest.
+
+### Example-1
+
+`angular.json`:
+
+```js
+"architect": {
+  ...
+  "build": {
+    "builder": "@angular-builders/custom-esbuild:application",
+    "options": {
+      "plugins": ["./esbuild/plugin-1.js"]
+      ...
+    }
+  },
+  "test": {
+    "builder": "@angular-builders/custom-esbuild:unit-test",
+    "options": {
+      "buildTarget": "my-project:build",
+      "tsConfig": "src/tsconfig.spec.json"
+    }
+  }
+}
+```
+
 # Index Transform
 
 Since Angular 8, `index.html` is not generated as part of the build. If you want to modify your `index.html`, you should use the `indexHtmlTransformer` option. `indexHtmlTransformer` is a path (relative to the workspace root) to a `.js` or `.ts` file that exports a transformation function for `index.html`. If `indexHtmlTransformer` is written in TypeScript, the application's `tsConfig` file will be used by `tsnode` for its execution:
diff --git a/packages/custom-esbuild/builders.json b/packages/custom-esbuild/builders.json
@@ -10,6 +10,11 @@
       "implementation": "./dist/dev-server",
       "schema": "./dist/dev-server/schema.json",
       "description": "Build browser app extended with custom esbuild config"
+    },
+    "unit-test": {
+      "implementation": "./dist/unit-test",
+      "schema": "./dist/unit-test/schema.json",
+      "description": "Run unit test extended with custom esbuild config"
     }
   }
 }
diff --git a/packages/custom-esbuild/e2e/custom-esbuild-schema.spec.ts b/packages/custom-esbuild/e2e/custom-esbuild-schema.spec.ts
@@ -3,11 +3,13 @@ import { resolvePackagePath } from '@angular-builders/common';
 describe('Custom ESBuild schema tests', () => {
   let customEsbuildApplicationSchema: any;
   let customEsbuildDevServerSchema: any;
+  let customEsbuildUnitTestSchema: any;
 
   beforeEach(() => {
     jest.resetModules();
     customEsbuildApplicationSchema = require('../dist/application/schema.json');
     customEsbuildDevServerSchema = require('../dist/dev-server/schema.json');
+    customEsbuildUnitTestSchema = require('../dist/unit-test/schema.json');
   });
 
   it('should fit the schema of the `@angular/build:application`', () => {
@@ -24,4 +26,12 @@ describe('Custom ESBuild schema tests', () => {
     customEsbuildDevServerSchema.properties['middlewares'] = undefined;
     expect(originalDevServerSchema.properties).toEqual(customEsbuildDevServerSchema.properties);
   });
+
+  it('should fit the schema of the `@angular/build:unit-test` without `runner` property', () => {
+    const path = resolvePackagePath('@angular/build', 'src/builders/unit-test/schema.json');
+    const originalUnitTestSchema = require(path);
+    originalUnitTestSchema.properties['runner'] = undefined;
+    customEsbuildUnitTestSchema.properties['plugins'] = undefined;
+    expect(originalUnitTestSchema.properties).toEqual(customEsbuildUnitTestSchema.properties);
+  });
 });
diff --git a/packages/custom-esbuild/package.json b/packages/custom-esbuild/package.json
@@ -41,15 +41,15 @@
   "builders": "builders.json",
   "dependencies": {
     "@angular-builders/common": "workspace:*",
-    "@angular-devkit/architect": ">=0.2000.0 < 0.2100.0",
-    "@angular-devkit/core": "^20.0.0",
-    "@angular/build": "^20.0.0"
+    "@angular-devkit/architect": ">=0.2001.0 < 0.2100.0",
+    "@angular-devkit/core": "^20.1.0",
+    "@angular/build": "^20.1.0"
   },
   "peerDependencies": {
     "@angular/compiler-cli": "^20.0.0"
   },
   "devDependencies": {
-    "esbuild": "0.25.1",
+    "esbuild": "0.25.9",
     "jest": "29.7.0",
     "rimraf": "^5.0.0",
     "ts-node": "^10.0.0",
diff --git a/packages/custom-esbuild/src/custom-esbuild-schema.ts b/packages/custom-esbuild/src/custom-esbuild-schema.ts
@@ -1,12 +1,21 @@
-import { ApplicationBuilderOptions, DevServerBuilderOptions } from '@angular/build';
+import {
+  ApplicationBuilderOptions,
+  DevServerBuilderOptions,
+  UnitTestBuilderOptions,
+} from '@angular/build';
 
 export type PluginConfig = string | { path: string; options?: Record<string, unknown> };
 
 export type CustomEsbuildApplicationSchema = ApplicationBuilderOptions & {
-  plugins?: string[];
+  plugins?: PluginConfig[];
   indexHtmlTransformer?: string;
 };
 
 export type CustomEsbuildDevServerSchema = DevServerBuilderOptions & {
   middlewares?: string[];
 };
+
+// Omitting `runner` here as we only support `vitest` runner (`karma` runner doesn't support ESBuild plugins)
+export type CustomEsbuildUnitTestSchema = Omit<UnitTestBuilderOptions, 'runner'> & {
+  plugins?: PluginConfig[];
+};
diff --git a/packages/custom-esbuild/src/index.ts b/packages/custom-esbuild/src/index.ts
@@ -1,2 +1,3 @@
 export * from './application';
 export * from './dev-server';
+export * from './unit-test';
diff --git a/packages/custom-esbuild/src/load-plugins.ts b/packages/custom-esbuild/src/load-plugins.ts
@@ -5,6 +5,7 @@ import { loadModule } from '@angular-builders/common';
 import {
   CustomEsbuildApplicationSchema,
   CustomEsbuildDevServerSchema,
+  CustomEsbuildUnitTestSchema,
   PluginConfig,
 } from './custom-esbuild-schema';
 import { Target } from '@angular-devkit/architect';
@@ -14,7 +15,7 @@ export async function loadPlugins(
   workspaceRoot: string,
   tsConfig: string,
   logger: logging.LoggerApi,
-  builderOptions: CustomEsbuildApplicationSchema | CustomEsbuildDevServerSchema,
+  builderOptions: CustomEsbuildApplicationSchema | CustomEsbuildDevServerSchema | CustomEsbuildUnitTestSchema,
   target: Target
 ): Promise<Plugin[]> {
   const plugins = await Promise.all(
diff --git a/packages/custom-esbuild/src/schemes.ts b/packages/custom-esbuild/src/schemes.ts
@@ -1,4 +1,4 @@
-// Base schemes from @angular/build@20.0.0
+// Base schemes from @angular/build@20.1.0
 module.exports = [
   {
     originalSchemaPackage: '@angular/build',
@@ -12,4 +12,10 @@ module.exports = [
     schemaExtensionPaths: [`${__dirname}/dev-server/schema.ext.json`],
     newSchemaPath: `${__dirname}/../dist/dev-server/schema.json`,
   },
+  {
+    originalSchemaPackage: '@angular/build',
+    originalSchemaPath: 'src/builders/unit-test/schema.json',
+    schemaExtensionPaths: [`${__dirname}/unit-test/schema.ext.json`],
+    newSchemaPath: `${__dirname}/../dist/unit-test/schema.json`,
+  },
 ];
diff --git a/packages/custom-esbuild/src/unit-test/index.ts b/packages/custom-esbuild/src/unit-test/index.ts
@@ -0,0 +1,53 @@
+import * as path from 'node:path';
+import { BuilderContext, createBuilder, targetFromTargetString } from '@angular-devkit/architect';
+import { executeUnitTestBuilder, UnitTestBuilderOptions } from '@angular/build';
+import { getSystemPath, json, normalize } from '@angular-devkit/core';
+import { from, switchMap } from 'rxjs';
+
+import { loadPlugins } from '../load-plugins';
+import {
+  CustomEsbuildApplicationSchema,
+  CustomEsbuildUnitTestSchema,
+} from '../custom-esbuild-schema';
+
+export function executeCustomEsbuildUnitTestBuilder(
+  options: CustomEsbuildUnitTestSchema,
+  context: BuilderContext
+) {
+  const buildTarget = targetFromTargetString(options.buildTarget);
+
+  async function getBuildTargetOptions() {
+    return (await context.getTargetOptions(
+      buildTarget
+    )) as unknown as CustomEsbuildApplicationSchema;
+  }
+
+  const workspaceRoot = getSystemPath(normalize(context.workspaceRoot));
+  const tsConfig = path.join(workspaceRoot, options.tsConfig);
+
+  return from(getBuildTargetOptions()).pipe(
+    switchMap(async buildOptions => {
+      const codePlugins = await loadPlugins(
+        buildOptions.plugins,
+        workspaceRoot,
+        tsConfig,
+        context.logger,
+        options,
+        context.target
+      );
+
+      return { codePlugins };
+    }),
+    switchMap(extensions =>
+      executeUnitTestBuilder(
+        { ...options, runner: 'vitest' as UnitTestBuilderOptions['runner'] },
+        context,
+        extensions
+      )
+    )
+  );
+}
+
+export default createBuilder<json.JsonObject & CustomEsbuildUnitTestSchema>(
+  executeCustomEsbuildUnitTestBuilder
+);
diff --git a/packages/custom-esbuild/src/unit-test/schema.ext.json b/packages/custom-esbuild/src/unit-test/schema.ext.json
@@ -0,0 +1,35 @@
+{
+  "$id": "UnitTestCustomApplicationSchema",
+  "title": "Custom application schema for Unit Test Facade",
+  "description": "Unit testing options for Angular applications.",
+  "properties": {
+    "runner": "__DELETE__",
+    "plugins": {
+      "type": "array",
+      "description": "A list of paths to ESBuild plugins",
+      "default": [],
+      "items": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string"
+              },
+              "options": {
+                "type": "object"
+              }
+            },
+            "required": [
+              "path"
+            ]
+          }
+        ],
+        "uniqueItems": true
+      }
+    }
+  }
+}
diff --git a/packages/custom-webpack/package.json b/packages/custom-webpack/package.json
@@ -41,15 +41,15 @@
   "builders": "builders.json",
   "dependencies": {
     "@angular-builders/common": "workspace:*",
-    "@angular-devkit/architect": ">=0.2000.0 < 0.2100.0",
-    "@angular-devkit/build-angular": "^20.0.0",
-    "@angular-devkit/core": "^20.0.0",
-    "@angular/build": "^20.0.0",
+    "@angular-devkit/architect": ">=0.2001.0 < 0.2100.0",
+    "@angular-devkit/build-angular": "^20.1.0",
+    "@angular-devkit/core": "^20.1.0",
+    "@angular/build": "^20.1.0",
     "lodash": "^4.17.15",
     "webpack-merge": "^6.0.0"
   },
   "peerDependencies": {
-    "@angular/compiler-cli": "^20.0.0"
+    "@angular/compiler-cli": "^20.1.0"
   },
   "devDependencies": {
     "jest": "29.7.0",
diff --git a/packages/jest/package.json b/packages/jest/package.json
@@ -43,8 +43,8 @@
   },
   "dependencies": {
     "@angular-builders/common": "workspace:*",
-    "@angular-devkit/architect": ">=0.2000.0 < 0.2100.0",
-    "@angular-devkit/core": "^20.0.0",
+    "@angular-devkit/architect": ">=0.2001.0 < 0.2100.0",
+    "@angular-devkit/core": "^20.1.0",
     "jest-preset-angular": "14.6.0",
     "lodash": "^4.17.15"
   },
diff --git a/packages/timestamp/package.json b/packages/timestamp/package.json
@@ -29,8 +29,8 @@
     "generate": "quicktype -s schema src/schema.json -o src/schema.ts"
   },
   "dependencies": {
-    "@angular-devkit/architect": ">=0.2000.0 < 0.2100.0",
-    "@angular-devkit/core": "^20.0.0",
+    "@angular-devkit/architect": ">=0.2001.0 < 0.2100.0",
+    "@angular-devkit/core": "^20.1.0",
     "dateformat": "^5.0.3"
   },
   "devDependencies": {
diff --git a/yarn.lock b/yarn.lock

Original file line number	Diff line number	Diff line change
`@@ -10,6 +10,11 @@`
`10`	`10`	`"implementation": "./dist/dev-server",`
`11`	`11`	`"schema": "./dist/dev-server/schema.json",`
`12`	`12`	`"description": "Build browser app extended with custom esbuild config"`
	`13`	`+ },`
	`14`	`+ "unit-test": {`
	`15`	`+ "implementation": "./dist/unit-test",`
	`16`	`+ "schema": "./dist/unit-test/schema.json",`
	`17`	`+ "description": "Run unit test extended with custom esbuild config"`
`13`	`18`	`}`
`14`	`19`	`}`
`15`	`20`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`export * from './application';`
`2`	`2`	`export * from './dev-server';`
	`3`	`+export * from './unit-test';`