refactor: add entryPoints to browser-esbuild as an internal option

This makes the `main` parameter optional and allows multiple entry points instead. `main` is still technically required by the schema, since it should almost always be set when invoked by a user. However, it now supports `null` as a value so it can be explicitly omitted.

Longer term, we may choose to remove `main` and fold it into `entryPoints`, but for now we want to keep compatibility with the existing `browser` builder.

Since `entryPoints` is an internal-only options (cannot be set in `angular.json` and isn't exposed in the schema), I made a new `buildEsbuildBrowserInternal()` function which adds the extra private option. This way direct invocations of the builder can provide this extra information without compromising the public API surface defined in the schema.

(cherry picked from commit 71e87fc)

Author: dgp1130

packages/angular_devkit/build_angular/src/builders/browser-esbuild/experimental-warnings.ts

@@ -8,7 +8,7 @@
 
 import { BuilderContext } from '@angular-devkit/architect';
 import { Schema as BrowserBuilderOptions } from '../browser/schema';
-import { Schema as BrowserEsbuildOptions } from './schema';
+import { BrowserEsbuildOptions } from './options';
 
 const UNSUPPORTED_OPTIONS: Array<keyof BrowserBuilderOptions> = [
   'budgets',

packages/angular_devkit/build_angular/src/builders/browser-esbuild/index.ts

@@ -28,7 +28,7 @@ import { logExperimentalWarnings } from './experimental-warnings';
 import { createGlobalScriptsBundleOptions } from './global-scripts';
 import { extractLicenses } from './license-extractor';
 import { LoadResultCache } from './load-result-cache';
-import { NormalizedBrowserOptions, normalizeOptions } from './options';
+import { BrowserEsbuildOptions, NormalizedBrowserOptions, normalizeOptions } from './options';
 import { shutdownSassWorkerPool } from './sass-plugin';
 import { Schema as BrowserBuilderOptions } from './schema';
 import { createStylesheetBundleOptions } from './stylesheets';
@@ -584,7 +584,7 @@ async function withNoProgress<T>(test: string, action: () => T | Promise<T>): Pr
  * @param context The Architect builder context object
  * @returns An async iterable with the builder result output
  */
-export async function* buildEsbuildBrowser(
+export function buildEsbuildBrowser(
   userOptions: BrowserBuilderOptions,
   context: BuilderContext,
   infrastructureSettings?: {
@@ -595,6 +595,28 @@ export async function* buildEsbuildBrowser(
     outputFiles?: OutputFile[];
     assetFiles?: { source: string; destination: string }[];
   }
+> {
+  return buildEsbuildBrowserInternal(userOptions, context, infrastructureSettings);
+}
+
+/**
+ * Internal version of the main execution function for the esbuild-based application builder.
+ * Exposes some additional "private" options in addition to those exposed by the schema.
+ * @param userOptions The browser-esbuild builder options to use when setting up the application build
+ * @param context The Architect builder context object
+ * @returns An async iterable with the builder result output
+ */
+export async function* buildEsbuildBrowserInternal(
+  userOptions: BrowserEsbuildOptions,
+  context: BuilderContext,
+  infrastructureSettings?: {
+    write?: boolean;
+  },
+): AsyncIterable<
+  BuilderOutput & {
+    outputFiles?: OutputFile[];
+    assetFiles?: { source: string; destination: string }[];
+  }
 > {
   // Inform user of experimental status of builder and options
   logExperimentalWarnings(userOptions, context);

packages/angular_devkit/build_angular/src/builders/browser-esbuild/options.ts

@@ -20,6 +20,23 @@ import { Schema as BrowserBuilderOptions, OutputHashing } from './schema';
 
 export type NormalizedBrowserOptions = Awaited<ReturnType<typeof normalizeOptions>>;
 
+/** Internal options hidden from builder schema but available when invoked programmatically. */
+interface InternalOptions {
+  /**
+   * Entry points to use for the compilation. Incompatible with `main`, which must not be provided. May be relative or absolute paths.
+   * If given a relative path, it is resolved relative to the current workspace and will generate an output at the same relative location
+   * in the output directory. If given an absolute path, the output will be generated in the root of the output directory with the same base
+   * name.
+   */
+  entryPoints?: Set<string>;
+}
+
+/** Full set of options for `browser-esbuild` builder. */
+export type BrowserEsbuildOptions = Omit<BrowserBuilderOptions & InternalOptions, 'main'> & {
+  // `main` can be `undefined` if `entryPoints` is used.
+  main?: string;
+};
+
 /**
  * Normalize the user provided options by creating full paths for all path based options
  * and converting multi-form options into a single form that can be directly used
@@ -33,7 +50,7 @@ export type NormalizedBrowserOptions = Awaited<ReturnType<typeof normalizeOption
 export async function normalizeOptions(
   context: BuilderContext,
   projectName: string,
-  options: BrowserBuilderOptions,
+  options: BrowserEsbuildOptions,
 ) {
   const workspaceRoot = context.workspaceRoot;
   const projectMetadata = await context.getProjectMetadata(projectName);
@@ -46,7 +63,7 @@ export async function normalizeOptions(
 
   const cacheOptions = normalizeCacheOptions(projectMetadata, workspaceRoot);
 
-  const mainEntryPoint = path.join(workspaceRoot, options.main);
+  const entryPoints = normalizeEntryPoints(workspaceRoot, options.main, options.entryPoints);
   const tsconfig = path.join(workspaceRoot, options.tsConfig);
   const outputPath = normalizeDirectoryPath(path.join(workspaceRoot, options.outputPath));
   const optimizationOptions = normalizeOptimization(options.optimization);
@@ -125,11 +142,6 @@ export async function normalizeOptions(
       : path.join(projectRoot, 'ngsw-config.json');
   }
 
-  // Setup bundler entry points
-  const entryPoints: Record<string, string> = {
-    main: mainEntryPoint,
-  };
-
   let indexHtmlOptions;
   if (options.index) {
     indexHtmlOptions = {
@@ -204,6 +216,57 @@ export async function normalizeOptions(
   };
 }
 
+/**
+ * Normalize entry point options. To maintain compatibility with the legacy browser builder, we need a single `main` option which defines a
+ * single entry point. However, we also want to support multiple entry points as an internal option. The two options are mutually exclusive
+ * and if `main` is provided it will be used as the sole entry point. If `entryPoints` are provided, they will be used as the set of entry
+ * points.
+ *
+ * @param workspaceRoot Path to the root of the Angular workspace.
+ * @param main The `main` option pointing at the application entry point. While required per the schema file, it may be omitted by
+ *     programmatic usages of `browser-esbuild`.
+ * @param entryPoints Set of entry points to use if provided.
+ * @returns An object mapping entry point names to their file paths.
+ */
+function normalizeEntryPoints(
+  workspaceRoot: string,
+  main: string | undefined,
+  entryPoints: Set<string> = new Set(),
+): Record<string, string> {
+  if (main === '') {
+    throw new Error('`main` option cannot be an empty string.');
+  }
+
+  // `main` and `entryPoints` are mutually exclusive.
+  if (main && entryPoints.size > 0) {
+    throw new Error('Only one of `main` or `entryPoints` may be provided.');
+  }
+  if (!main && entryPoints.size === 0) {
+    // Schema should normally reject this case, but programmatic usages of the builder might make this mistake.
+    throw new Error('Either `main` or at least one `entryPoints` value must be provided.');
+  }
+
+  // Schema types force `main` to always be provided, but it may be omitted when the builder is invoked programmatically.
+  if (main) {
+    // Use `main` alone.
+    return { 'main': path.join(workspaceRoot, main) };
+  } else {
+    // Use `entryPoints` alone.
+    return Object.fromEntries(
+      Array.from(entryPoints).map((entryPoint) => {
+        const parsedEntryPoint = path.parse(entryPoint);
+
+        return [
+          // File path without extension.
+          path.join(parsedEntryPoint.dir, parsedEntryPoint.name),
+          // Full file path.
+          path.join(workspaceRoot, entryPoint),
+        ];
+      }),
+    );
+  }
+}
+
 /**
  * Normalize a directory path string.
  * Currently only removes a trailing slash if present.

packages/angular_devkit/build_angular/src/builders/browser-esbuild/tests/options/entry-points_spec.ts

@@ -0,0 +1,66 @@
+/**
+ * @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 { buildEsbuildBrowserInternal } from '../../index';
+import { BASE_OPTIONS, BROWSER_BUILDER_INFO, describeBuilder } from '../setup';
+
+describeBuilder(buildEsbuildBrowserInternal, BROWSER_BUILDER_INFO, (harness) => {
+  describe('Option: "entryPoints"', () => {
+    it('provides multiple entry points', async () => {
+      await harness.writeFiles({
+        'src/entry1.ts': `console.log('entry1');`,
+        'src/entry2.ts': `console.log('entry2');`,
+        'tsconfig.app.json': `
+          {
+            "extends": "./tsconfig.json",
+            "files": ["src/entry1.ts", "src/entry2.ts"]
+          }
+        `,
+      });
+
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        main: undefined,
+        tsConfig: 'tsconfig.app.json',
+        entryPoints: new Set(['src/entry1.ts', 'src/entry2.ts']),
+      });
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBeTrue();
+
+      harness.expectFile('dist/entry1.js').toExist();
+      harness.expectFile('dist/entry2.js').toExist();
+    });
+
+    it('throws when `main` is omitted and an empty `entryPoints` Set is provided', async () => {
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        main: undefined,
+        entryPoints: new Set(),
+      });
+
+      const { result, error } = await harness.executeOnce();
+      expect(result).toBeUndefined();
+
+      expect(error?.message).toContain('Either `main` or at least one `entryPoints`');
+    });
+
+    it('throws when provided with a `main` option', async () => {
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        main: 'src/main.ts',
+        entryPoints: new Set(['src/entry.ts']),
+      });
+
+      const { result, error } = await harness.executeOnce();
+      expect(result).toBeUndefined();
+
+      expect(error?.message).toContain('Only one of `main` or `entryPoints` may be provided.');
+    });
+  });
+});

packages/angular_devkit/build_angular/src/builders/browser-esbuild/tests/options/main_spec.ts

@@ -59,5 +59,17 @@ describeBuilder(buildEsbuildBrowser, BROWSER_BUILDER_INFO, (harness) => {
       harness.expectFile('dist/main.js').toNotExist();
       harness.expectFile('dist/index.html').toNotExist();
     });
+
+    it('throws an error when given an empty string', async () => {
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        main: '',
+      });
+
+      const { result, error } = await harness.executeOnce();
+      expect(result).toBeUndefined();
+
+      expect(error?.message).toContain('cannot be an empty string');
+    });
   });
 });