feat(@angular-devkit/build-angular): allow customization of output locations

This update introduces the ability for users to define the locations for storing `media`, `browser`, and `server` files.

You can achieve this by utilizing the extended `outputPath` option.
```json
{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@angular-devkit/build-angular:application",
          "options": {
            "outputPath": {
              "base": "dist/my-app",
              "browser": "",
              "server": "node-server",
              "media": "resources"
            }
          }
        }
      }
    }
  }
}
```

While not recommended, choosing to set the `browser` option empty will result in files being output directly under the specified `base` path. It's important to note that this action will generate certain files like `stats.json` and `prerendered-routes.json` that aren't intended for deployment in this directory.

**Validation rules:**
- `browser` and `server` are relative to the configuration set in the `base` option.
- When SSR is enabled, `browser` cannot be set to an empty string, and cannot be the same as `server`.
- `media` is relative to the value specified in the `browser` option.
- `media` cannot be set to an empty string.
- `browser`, `media`, or `server` cannot contain slashes.

Closes: angular#26632 and closes: angular#26057

Author: alan-agius4

goldens/public-api/angular_devkit/build_angular/index.md

@@ -46,7 +46,7 @@ export interface ApplicationBuilderOptions {
     namedChunks?: boolean;
     optimization?: OptimizationUnion_2;
     outputHashing?: OutputHashing_2;
-    outputPath: string;
+    outputPath: OutputPathUnion;
     poll?: number;
     polyfills?: string[];
     prerender?: PrerenderUnion;
@@ -149,13 +149,10 @@ export interface Budget {
 }
 
 // @public
-export function buildApplication(options: ApplicationBuilderOptions, context: BuilderContext, plugins?: Plugin_2[]): AsyncIterable<BuilderOutput & {
-    outputFiles?: BuildOutputFile[];
-    assetFiles?: {
-        source: string;
-        destination: string;
-    }[];
-}>;
+export function buildApplication(options: ApplicationBuilderOptions, context: BuilderContext, plugins?: Plugin_2[]): AsyncIterable<ApplicationBuilderOutput>;
+
+// @public
+export function buildApplication(options: ApplicationBuilderOptions, context: BuilderContext, extensions?: ApplicationBuilderExtensions): AsyncIterable<ApplicationBuilderOutput>;
 
 // @public
 export enum CrossOrigin {

packages/angular_devkit/build_angular/src/builders/application/build-action.ts

@@ -17,17 +17,18 @@ import { withNoProgress, withSpinner, writeResultFiles } from '../../tools/esbui
 import { deleteOutputDir } from '../../utils/delete-output-dir';
 import { shouldWatchRoot } from '../../utils/environment-options';
 import { NormalizedCachedOptions } from '../../utils/normalize-cache';
+import { NormalizedOutputOptions } from './options';
 
 export async function* runEsBuildBuildAction(
   action: (rebuildState?: RebuildState) => ExecutionResult | Promise<ExecutionResult>,
   options: {
     workspaceRoot: string;
     projectRoot: string;
-    outputPath: string;
+    outputOptions: NormalizedOutputOptions;
     logger: logging.LoggerApi;
     cacheOptions: NormalizedCachedOptions;
-    writeToFileSystem?: boolean;
-    writeToFileSystemFilter?: (file: BuildOutputFile) => boolean;
+    writeToFileSystem: boolean;
+    writeToFileSystemFilter: ((file: BuildOutputFile) => boolean) | undefined;
     watch?: boolean;
     verbose?: boolean;
     progress?: boolean;
@@ -39,13 +40,13 @@ export async function* runEsBuildBuildAction(
 ): AsyncIterable<(ExecutionResult['outputWithFiles'] | ExecutionResult['output']) & BuilderOutput> {
   const {
     writeToFileSystemFilter,
-    writeToFileSystem = true,
+    writeToFileSystem,
     watch,
     poll,
     logger,
     deleteOutputPath,
     cacheOptions,
-    outputPath,
+    outputOptions,
     verbose,
     projectRoot,
     workspaceRoot,
@@ -54,7 +55,10 @@ export async function* runEsBuildBuildAction(
   } = options;
 
   if (deleteOutputPath && writeToFileSystem) {
-    await deleteOutputDir(workspaceRoot, outputPath, ['browser', 'server']);
+    await deleteOutputDir(workspaceRoot, outputOptions.base, [
+      outputOptions.browser,
+      outputOptions.server,
+    ]);
   }
 
   const withProgress: typeof withSpinner = progress ? withSpinner : withNoProgress;
@@ -79,7 +83,7 @@ export async function* runEsBuildBuildAction(
 
     const ignored: string[] = [
       // Ignore the output and cache paths to avoid infinite rebuild cycles
-      outputPath,
+      outputOptions.base,
       cacheOptions.basePath,
       `${workspaceRoot.replace(/\\/g, '/')}/**/.*/**`,
     ];
@@ -137,7 +141,7 @@ export async function* runEsBuildBuildAction(
   // unit tests which execute the builder and modify the file system programmatically.
   if (writeToFileSystem) {
     // Write output files
-    await writeResultFiles(result.outputFiles, result.assetFiles, outputPath);
+    await writeResultFiles(result.outputFiles, result.assetFiles, outputOptions);
 
     yield result.output;
   } else {
@@ -191,7 +195,7 @@ export async function* runEsBuildBuildAction(
         const filesToWrite = writeToFileSystemFilter
           ? result.outputFiles.filter(writeToFileSystemFilter)
           : result.outputFiles;
-        await writeResultFiles(filesToWrite, result.assetFiles, outputPath);
+        await writeResultFiles(filesToWrite, result.assetFiles, outputOptions);
 
         yield result.output;
       } else {

packages/angular_devkit/build_angular/src/builders/application/index.ts

@@ -13,7 +13,11 @@ import { purgeStaleBuildCache } from '../../utils/purge-cache';
 import { assertCompatibleAngularVersion } from '../../utils/version';
 import { runEsBuildBuildAction } from './build-action';
 import { executeBuild } from './execute-build';
-import { ApplicationBuilderInternalOptions, normalizeOptions } from './options';
+import {
+  ApplicationBuilderExtensions,
+  ApplicationBuilderInternalOptions,
+  normalizeOptions,
+} from './options';
 import { Schema as ApplicationBuilderOptions } from './schema';
 
 export { ApplicationBuilderOptions };
@@ -25,28 +29,49 @@ export async function* buildApplicationInternal(
   infrastructureSettings?: {
     write?: boolean;
   },
-  plugins?: Plugin[],
-): AsyncIterable<
-  BuilderOutput & {
-    outputFiles?: BuildOutputFile[];
-    assetFiles?: { source: string; destination: string }[];
-  }
-> {
+  extensions?: ApplicationBuilderExtensions,
+): AsyncIterable<ApplicationBuilderOutput> {
+  const { workspaceRoot, logger, target } = context;
+
   // Check Angular version.
-  assertCompatibleAngularVersion(context.workspaceRoot);
+  assertCompatibleAngularVersion(workspaceRoot);
 
   // Purge old build disk cache.
   await purgeStaleBuildCache(context);
 
   // Determine project name from builder context target
-  const projectName = context.target?.project;
+  const projectName = target?.project;
   if (!projectName) {
-    context.logger.error(`The 'application' builder requires a target to be specified.`);
+    yield { success: false, error: `The 'application' builder requires a target to be specified.` };
 
     return;
   }
 
-  const normalizedOptions = await normalizeOptions(context, projectName, options, plugins);
+  const normalizedOptions = await normalizeOptions(context, projectName, options, extensions);
+  const writeToFileSystem = infrastructureSettings?.write ?? true;
+  const writeServerBundles =
+    writeToFileSystem && !!(normalizedOptions.ssrOptions && normalizedOptions.serverEntryPoint);
+
+  if (writeServerBundles) {
+    const { browser, server } = normalizedOptions.outputOptions;
+    if (browser === '') {
+      yield {
+        success: false,
+        error: `'outputPath.browser' cannot be configured to an empty string when SSR is enabled.`,
+      };
+
+      return;
+    }
+
+    if (browser === server) {
+      yield {
+        success: false,
+        error: `'outputPath.browser' and 'outputPath.server' cannot be configured to the same value.`,
+      };
+
+      return;
+    }
+  }
 
   // Setup an abort controller with a builder teardown if no signal is present
   let signal = context.signal;
@@ -59,14 +84,11 @@ export async function* buildApplicationInternal(
   yield* runEsBuildBuildAction(
     async (rebuildState) => {
       const startTime = process.hrtime.bigint();
-
       const result = await executeBuild(normalizedOptions, context, rebuildState);
 
       const buildTime = Number(process.hrtime.bigint() - startTime) / 10 ** 9;
       const status = result.errors.length > 0 ? 'failed' : 'complete';
-      context.logger.info(
-        `Application bundle generation ${status}. [${buildTime.toFixed(3)} seconds]`,
-      );
+      logger.info(`Application bundle generation ${status}. [${buildTime.toFixed(3)} seconds]`);
 
       return result;
     },
@@ -76,24 +98,28 @@ export async function* buildApplicationInternal(
       poll: normalizedOptions.poll,
       deleteOutputPath: normalizedOptions.deleteOutputPath,
       cacheOptions: normalizedOptions.cacheOptions,
-      outputPath: normalizedOptions.outputPath,
+      outputOptions: normalizedOptions.outputOptions,
       verbose: normalizedOptions.verbose,
       projectRoot: normalizedOptions.projectRoot,
       workspaceRoot: normalizedOptions.workspaceRoot,
       progress: normalizedOptions.progress,
-      writeToFileSystem: infrastructureSettings?.write,
+      writeToFileSystem,
       // For app-shell and SSG server files are not required by users.
       // Omit these when SSR is not enabled.
-      writeToFileSystemFilter:
-        normalizedOptions.ssrOptions && normalizedOptions.serverEntryPoint
-          ? undefined
-          : (file) => file.type !== BuildOutputFileType.Server,
-      logger: context.logger,
+      writeToFileSystemFilter: writeServerBundles
+        ? undefined
+        : (file) => file.type !== BuildOutputFileType.Server,
+      logger,
       signal,
     },
   );
 }
 
+export interface ApplicationBuilderOutput extends BuilderOutput {
+  outputFiles?: BuildOutputFile[];
+  assetFiles?: { source: string; destination: string }[];
+}
+
 /**
  * Builds an application using the `application` builder with the provided
  * options.
@@ -112,13 +138,41 @@ export function buildApplication(
   options: ApplicationBuilderOptions,
   context: BuilderContext,
   plugins?: Plugin[],
-): AsyncIterable<
-  BuilderOutput & {
-    outputFiles?: BuildOutputFile[];
-    assetFiles?: { source: string; destination: string }[];
+): AsyncIterable<ApplicationBuilderOutput>;
+
+/**
+ * Builds an application using the `application` builder with the provided
+ * options.
+ *
+ * Usage of the `extensions` parameter is NOT supported and may cause unexpected
+ * build output or build failures.
+ *
+ * @experimental Direct usage of this function is considered experimental.
+ *
+ * @param options The options defined by the builder's schema to use.
+ * @param context An Architect builder context instance.
+ * @param extensions An object contain extension points for the build.
+ * @returns The build output results of the build.
+ */
+export function buildApplication(
+  options: ApplicationBuilderOptions,
+  context: BuilderContext,
+  extensions?: ApplicationBuilderExtensions,
+): AsyncIterable<ApplicationBuilderOutput>;
+
+export function buildApplication(
+  options: ApplicationBuilderOptions,
+  context: BuilderContext,
+  pluginsOrExtensions?: Plugin[] | ApplicationBuilderExtensions,
+): AsyncIterable<ApplicationBuilderOutput> {
+  let extensions;
+  if (pluginsOrExtensions && Array.isArray(pluginsOrExtensions)) {
+    extensions = {
+      codePlugins: pluginsOrExtensions,
+    };
   }
-> {
-  return buildApplicationInternal(options, context, undefined, plugins);
+
+  return buildApplicationInternal(options, context, undefined, extensions);
 }
 
 export default createBuilder(buildApplication);