feat(@angular-devkit/build-angular): add initial experimental esbuild-based application browser builder

An experimental browser application builder (`browser-esbuild`) has been introduced that leverages esbuild as the bundler.
This new builder is compatible with options of the current browser application builder (`browser`) and can be enabled
for experimentation purposes by replacing the `builder` field of `@angular-devkit/build-angular:browser` from an existing
project to `@angular-devkit/build-angular:browser-esbuild`. The builder will generate an ESM-based application output
and is currently limited to an ES2020 compatible output.

This builder is considered experimental and is not recommended for production applications.

Currently not all `browser` builder options and capabilities are supported with this experimental builder.
Those that are unsupported will be ignored with a warning. Additional support for these options may be added in the future.
The following options and capabilities are not currently supported:
* Stylesheet Preprocessors (only CSS styles are supported)
* Angular JIT mode (only AOT is supported)
* Localization [`localize`]
* Watch and dev-server modes [`watch`, `poll`, etc.]
* File replacements [`fileReplacements`]
* License text extraction [`extractLicenses`]
* Bundle budgets [`budgets`]
* Global scripts [`scripts`]
* Build stats JSON output [`statsJson`]
* Deploy URL [`deployURL`]
* CommonJS module warnings (no warnings will be generated for CommonJS package usage)
* Web Workers
* Service workers [`serviceWorker`, `ngswConfigPath`]

Author: clydin

packages/angular_devkit/build_angular/builders.json

@@ -11,6 +11,11 @@
       "schema": "./src/builders/browser/schema.json",
       "description": "Build a browser application."
     },
+    "browser-esbuild": {
+      "implementation": "./src/builders/browser-esbuild",
+      "schema": "./src/builders/browser/schema.json",
+      "description": "Build a browser application."
+    },
     "dev-server": {
       "implementation": "./src/builders/dev-server",
       "schema": "./src/builders/dev-server/schema.json",

packages/angular_devkit/build_angular/src/babel/webpack-loader.ts

@@ -39,7 +39,7 @@ let linkerPluginCreator:
  */
 let i18nPluginCreators: I18nPluginCreators | undefined;
 
-async function requiresLinking(path: string, source: string): Promise<boolean> {
+export async function requiresLinking(path: string, source: string): Promise<boolean> {
   // @angular/core and @angular/compiler will cause false positives
   // Also, TypeScript files do not require linking
   if (/[\\/]@angular[\\/](?:compiler|core)|\.tsx?$/.test(path)) {

packages/angular_devkit/build_angular/src/builders/browser-esbuild/compiler-plugin.ts

@@ -0,0 +1,372 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import type { CompilerHost } from '@angular/compiler-cli';
+import { transformAsync } from '@babel/core';
+// Temporary deep import for transformer support
+import { createAotTransformers, mergeTransformers } from '@ngtools/webpack/src/ivy/transformation';
+import type { OnStartResult, PartialMessage, PartialNote, Plugin, PluginBuild } from 'esbuild';
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import ts from 'typescript';
+import { requiresLinking } from '../../babel/webpack-loader';
+import { loadEsmModule } from '../../utils/load-esm';
+import { BundleStylesheetOptions, bundleStylesheetData, bundleStylesheetFile } from './stylesheets';
+
+interface EmitFileResult {
+  content?: string;
+  map?: string;
+  dependencies: readonly string[];
+  hash?: Uint8Array;
+}
+type FileEmitter = (file: string) => Promise<EmitFileResult | undefined>;
+
+/**
+ * Converts TypeScript Diagnostic related information into an esbuild compatible note object.
+ * Related information is a subset of a full TypeScript Diagnostic and also used for diagnostic
+ * notes associated with the main Diagnostic.
+ * @param diagnostic The TypeScript diagnostic relative information to convert.
+ * @param host A TypeScript FormatDiagnosticsHost instance to use during conversion.
+ * @returns An esbuild diagnostic message as a PartialMessage object
+ */
+function convertTypeScriptDiagnosticInfo(
+  info: ts.DiagnosticRelatedInformation,
+  host: ts.FormatDiagnosticsHost,
+  textPrefix?: string,
+): PartialNote {
+  let text = ts.flattenDiagnosticMessageText(info.messageText, host.getNewLine());
+  if (textPrefix) {
+    text = textPrefix + text;
+  }
+
+  const note: PartialNote = { text };
+
+  if (info.file) {
+    note.location = {
+      file: info.file.fileName,
+      length: info.length,
+    };
+
+    if (info.start) {
+      const { line, character } = ts.getLineAndCharacterOfPosition(info.file, info.start);
+      note.location.line = line + 1;
+      note.location.column = character;
+      const { line: lastLine } = ts.getLineAndCharacterOfPosition(
+        info.file,
+        info.file.text.length - 1,
+      );
+      const lineStart = ts.getPositionOfLineAndCharacter(info.file, line, 0);
+      const lineEnd =
+        line < lastLine
+          ? ts.getPositionOfLineAndCharacter(info.file, line + 1, 0)
+          : info.file.text.length;
+      note.location.lineText = info.file.text.slice(lineStart, lineEnd).trimEnd();
+    }
+  }
+
+  return note;
+}
+
+/**
+ * Converts a TypeScript Diagnostic message into an esbuild compatible message object.
+ * @param diagnostic The TypeScript diagnostic to convert.
+ * @param host A TypeScript FormatDiagnosticsHost instance to use during conversion.
+ * @returns An esbuild diagnostic message as a PartialMessage object
+ */
+function convertTypeScriptDiagnostic(
+  diagnostic: ts.Diagnostic,
+  host: ts.FormatDiagnosticsHost,
+): PartialMessage {
+  let codePrefix = 'TS';
+  let code = `${diagnostic.code}`;
+  if (diagnostic.source === 'ngtsc') {
+    codePrefix = 'NG';
+    // Remove `-99` Angular prefix from diagnostic code
+    code = code.slice(3);
+  }
+
+  const message: PartialMessage = {
+    ...convertTypeScriptDiagnosticInfo(diagnostic, host, `${codePrefix}${code}: `),
+    // Store original diagnostic for reference if needed downstream
+    detail: diagnostic,
+  };
+
+  if (diagnostic.relatedInformation?.length) {
+    message.notes = diagnostic.relatedInformation.map((info) =>
+      convertTypeScriptDiagnosticInfo(info, host),
+    );
+  }
+
+  return message;
+}
+
+// This is a non-watch version of the compiler code from `@ngtools/webpack` augmented for esbuild
+// eslint-disable-next-line max-lines-per-function
+export function createCompilerPlugin(
+  pluginOptions: { sourcemap: boolean; tsconfig: string; advancedOptimizations?: boolean },
+  styleOptions: BundleStylesheetOptions,
+): Plugin {
+  return {
+    name: 'angular-compiler',
+    // eslint-disable-next-line max-lines-per-function
+    async setup(build: PluginBuild): Promise<void> {
+      // This uses a wrapped dynamic import to load `@angular/compiler-cli` which is ESM.
+      // Once TypeScript provides support for retaining dynamic imports this workaround can be dropped.
+      const compilerCli = await loadEsmModule<typeof import('@angular/compiler-cli')>(
+        '@angular/compiler-cli',
+      );
+
+      // Setup defines based on the values provided by the Angular compiler-cli
+      build.initialOptions.define ??= {};
+      for (const [key, value] of Object.entries(compilerCli.GLOBAL_DEFS_FOR_TERSER_WITH_AOT)) {
+        if (key in build.initialOptions.define) {
+          // Skip keys that have been manually provided
+          continue;
+        }
+        // esbuild requires values to be a string (actual strings need to be quoted).
+        // In this case, all provided values are booleans.
+        build.initialOptions.define[key] = `${value}`;
+      }
+
+      // The file emitter created during `onStart` that will be used during the build in `onLoad` callbacks for TS files
+      let fileEmitter: FileEmitter | undefined;
+
+      build.onStart(async () => {
+        const result: OnStartResult = {};
+
+        const {
+          options: compilerOptions,
+          rootNames,
+          errors,
+        } = compilerCli.readConfiguration(
+          pluginOptions.tsconfig,
+          // this.pluginOptions.compilerOptions,
+        );
+        compilerOptions.enableIvy = true;
+        compilerOptions.noEmitOnError = false;
+        compilerOptions.suppressOutputPathCheck = true;
+        compilerOptions.outDir = undefined;
+        compilerOptions.inlineSources = pluginOptions.sourcemap;
+        compilerOptions.inlineSourceMap = pluginOptions.sourcemap;
+        compilerOptions.sourceMap = false;
+        compilerOptions.mapRoot = undefined;
+        compilerOptions.sourceRoot = undefined;
+        compilerOptions.declaration = false;
+        compilerOptions.declarationMap = false;
+        compilerOptions.allowEmptyCodegenFiles = false;
+        compilerOptions.annotationsAs = 'decorators';
+        compilerOptions.enableResourceInlining = false;
+        if (compilerOptions.scriptTarget < ts.ScriptTarget.ES2015) {
+          compilerOptions.target = ts.ScriptTarget.ES2015;
+        }
+
+        // Create TypeScript compiler host
+        const host = ts.createIncrementalCompilerHost(compilerOptions);
+
+        const resourceHost = host as CompilerHost;
+
+        resourceHost.readResource = async function (fileName: string) {
+          if (fileName.endsWith('.html')) {
+            return this.readFile(fileName) ?? '';
+          }
+
+          const { contents, errors, warnings } = await bundleStylesheetFile(fileName, styleOptions);
+          (result.errors ??= []).push(...errors);
+          (result.warnings ??= []).push(...warnings);
+
+          return contents;
+        };
+
+        resourceHost.transformResource = async function (data, context) {
+          // Only style resources are supported currently
+          if (context.resourceFile || context.type !== 'style') {
+            return null;
+          }
+
+          const { contents, errors, warnings } = await bundleStylesheetData(
+            data,
+            {
+              resolvePath: path.dirname(context.containingFile),
+              virtualName: context.containingFile,
+            },
+            styleOptions,
+          );
+          (result.errors ??= []).push(...errors);
+          (result.warnings ??= []).push(...warnings);
+
+          return { content: contents };
+        };
+
+        // Create the Angular specific program that contains the Angular compiler
+        const angularProgram = new compilerCli.NgtscProgram(
+          rootNames,
+          compilerOptions,
+          host,
+          // this.ngtscNextProgram,
+        );
+        const angularCompiler = angularProgram.compiler;
+        const { ignoreForDiagnostics, ignoreForEmit } = angularCompiler;
+        const typeScriptProgram = angularProgram.getTsProgram();
+
+        const builder = ts.createAbstractBuilder(typeScriptProgram, host);
+
+        // Collect program level diagnostics
+        const diagnostics = [
+          ...angularCompiler.getOptionDiagnostics(),
+          ...builder.getOptionsDiagnostics(),
+          ...builder.getGlobalDiagnostics(),
+        ];
+
+        await angularCompiler.analyzeAsync();
+
+        // Collect source file specific diagnostics
+        const OptimizeFor = compilerCli.OptimizeFor;
+        for (const sourceFile of builder.getSourceFiles()) {
+          if (!ignoreForDiagnostics.has(sourceFile)) {
+            diagnostics.push(...builder.getSyntacticDiagnostics(sourceFile));
+            diagnostics.push(...builder.getSemanticDiagnostics(sourceFile));
+
+            const angularDiagnostics = angularCompiler.getDiagnosticsForFile(
+              sourceFile,
+              OptimizeFor.WholeProgram,
+            );
+            diagnostics.push(...angularDiagnostics);
+          }
+        }
+
+        for (const diagnostic of diagnostics) {
+          const message = convertTypeScriptDiagnostic(diagnostic, host);
+          if (diagnostic.category === ts.DiagnosticCategory.Error) {
+            (result.errors ??= []).push(message);
+          } else {
+            (result.warnings ??= []).push(message);
+          }
+        }
+
+        fileEmitter = createFileEmitter(
+          builder,
+          mergeTransformers(
+            angularCompiler.prepareEmit().transformers,
+            createAotTransformers(builder, {}),
+          ),
+          () => [],
+        );
+
+        return result;
+      });
+
+      build.onLoad({ filter: /\.[cm]?tsx?$/ }, async (args) => {
+        if (!fileEmitter) {
+          throw new Error('Invalid execution order');
+        }
+
+        const tsResult = await fileEmitter(args.path);
+        const data = tsResult?.content || '';
+        const babelResult = await transformAsync(data, {
+          filename: args.path,
+          inputSourceMap: (pluginOptions.sourcemap ? undefined : false) as undefined,
+          sourceMaps: pluginOptions.sourcemap ? 'inline' : false,
+          compact: false,
+          configFile: false,
+          babelrc: false,
+          browserslistConfigFile: false,
+          plugins: [],
+          presets: [
+            [
+              require('../../babel/presets/application').default,
+              {
+                forceAsyncTransformation: data.includes('async'),
+                optimize: pluginOptions.advancedOptimizations && {},
+              },
+            ],
+          ],
+        });
+
+        return {
+          contents: babelResult?.code ?? '',
+          loader: 'js',
+        };
+      });
+
+      build.onLoad({ filter: /\.[cm]?js$/ }, async (args) => {
+        const angularPackage = /[\\/]node_modules[\\/]@angular[\\/]/.test(args.path);
+
+        const linkerPluginCreator = (
+          await loadEsmModule<typeof import('@angular/compiler-cli/linker/babel')>(
+            '@angular/compiler-cli/linker/babel',
+          )
+        ).createEs2015LinkerPlugin;
+
+        const data = await fs.readFile(args.path, 'utf-8');
+        const result = await transformAsync(data, {
+          filename: args.path,
+          inputSourceMap: (pluginOptions.sourcemap ? undefined : false) as undefined,
+          sourceMaps: pluginOptions.sourcemap ? 'inline' : false,
+          compact: false,
+          configFile: false,
+          babelrc: false,
+          browserslistConfigFile: false,
+          plugins: [],
+          presets: [
+            [
+              require('../../babel/presets/application').default,
+              {
+                angularLinker: {
+                  shouldLink: await requiresLinking(args.path, data),
+                  jitMode: false,
+                  linkerPluginCreator,
+                },
+                forceAsyncTransformation:
+                  !/[\\/][_f]?esm2015[\\/]/.test(args.path) && data.includes('async'),
+                optimize: pluginOptions.advancedOptimizations && {
+                  looseEnums: angularPackage,
+                  pureTopLevel: angularPackage,
+                },
+              },
+            ],
+          ],
+        });
+
+        return {
+          contents: result?.code ?? data,
+          loader: 'js',
+        };
+      });
+    },
+  };
+}
+
+function createFileEmitter(
+  program: ts.BuilderProgram,
+  transformers: ts.CustomTransformers = {},
+  onAfterEmit?: (sourceFile: ts.SourceFile) => void,
+): FileEmitter {
+  return async (file: string) => {
+    const sourceFile = program.getSourceFile(file);
+    if (!sourceFile) {
+      return undefined;
+    }
+
+    let content: string | undefined;
+    program.emit(
+      sourceFile,
+      (filename, data) => {
+        if (/\.[cm]?js$/.test(filename)) {
+          content = data;
+        }
+      },
+      undefined,
+      undefined,
+      transformers,
+    );
+
+    onAfterEmit?.(sourceFile);
+
+    return { content, dependencies: [] };
+  };
+}