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.

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');
+    });
   });
 });