@angular/build 18.0.0-next.3

package/src/tools/esbuild/global-styles.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @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 { NormalizedApplicationBuildOptions } from '../../builders/application/options';
+import { BundlerOptionsFactory } from './bundler-context';
+export declare function createGlobalStylesBundleOptions(options: NormalizedApplicationBuildOptions, target: string[], initial: boolean): BundlerOptionsFactory | undefined;

package/src/tools/esbuild/global-styles.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * @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
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGlobalStylesBundleOptions = void 0;
+const node_assert_1 = __importDefault(require("node:assert"));
+const bundle_options_1 = require("./stylesheets/bundle-options");
+const virtual_module_plugin_1 = require("./virtual-module-plugin");
+function createGlobalStylesBundleOptions(options, target, initial) {
+    const { workspaceRoot, optimizationOptions, sourcemapOptions, outputNames, globalStyles, preserveSymlinks, externalDependencies, stylePreprocessorOptions, tailwindConfiguration, postcssConfiguration, cacheOptions, } = options;
+    const namespace = 'angular:styles/global';
+    const entryPoints = {};
+    let found = false;
+    for (const style of globalStyles) {
+        if (style.initial === initial) {
+            found = true;
+            entryPoints[style.name] = `${namespace};${style.name}`;
+        }
+    }
+    // Skip if there are no entry points for the style loading type
+    if (found === false) {
+        return;
+    }
+    return (loadCache) => {
+        const buildOptions = (0, bundle_options_1.createStylesheetBundleOptions)({
+            workspaceRoot,
+            optimization: !!optimizationOptions.styles.minify,
+            inlineFonts: !!optimizationOptions.fonts.inline,
+            sourcemap: !!sourcemapOptions.styles,
+            preserveSymlinks,
+            target,
+            externalDependencies,
+            outputNames: initial
+                ? outputNames
+                : {
+                    ...outputNames,
+                    bundles: '[name]',
+                },
+            includePaths: stylePreprocessorOptions?.includePaths,
+            tailwindConfiguration,
+            postcssConfiguration,
+            cacheOptions,
+        }, loadCache);
+        // Keep special CSS comments `/*! comment */` in place when `removeSpecialComments` is disabled.
+        // These comments are special for a number of CSS tools such as Critters and PurgeCSS.
+        buildOptions.legalComments = optimizationOptions.styles?.removeSpecialComments
+            ? 'none'
+            : 'inline';
+        buildOptions.entryPoints = entryPoints;
+        buildOptions.plugins.unshift((0, virtual_module_plugin_1.createVirtualModulePlugin)({
+            namespace,
+            transformPath: (path) => path.split(';', 2)[1],
+            loadContent: (args) => {
+                const files = globalStyles.find(({ name }) => name === args.path)?.files;
+                (0, node_assert_1.default)(files, `global style name should always be found [${args.path}]`);
+                return {
+                    contents: files.map((file) => `@import '${file.replace(/\\/g, '/')}';`).join('\n'),
+                    loader: 'css',
+                    resolveDir: workspaceRoot,
+                };
+            },
+        }));
+        return buildOptions;
+    };
+}
+exports.createGlobalStylesBundleOptions = createGlobalStylesBundleOptions;

package/src/tools/esbuild/i18n-inliner-worker.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @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
+ */
+/**
+ * The options passed to the inliner for each file request
+ */
+interface InlineRequest {
+    /**
+     * The filename that should be processed. The data for the file is provided to the Worker
+     * during Worker initialization.
+     */
+    filename: string;
+    /**
+     * The locale specifier that should be used during the inlining process of the file.
+     */
+    locale: string;
+    /**
+     * The translation messages for the locale that should be used during the inlining process of the file.
+     */
+    translation?: Record<string, unknown>;
+}
+/**
+ * Inlines the provided locale and translation into a JavaScript file that contains `$localize` usage.
+ * This function is the main entry for the Worker's action that is called by the worker pool.
+ *
+ * @param request An InlineRequest object representing the options for inlining
+ * @returns An array containing the inlined file and optional map content.
+ */
+export default function inlineLocale(request: InlineRequest): Promise<{
+    file: string;
+    code: string;
+    map: string | undefined;
+    messages: {
+        type: "error" | "warning";
+        message: string;
+    }[];
+}>;
+export {};

package/src/tools/esbuild/i18n-inliner-worker.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * @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
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const remapping_1 = __importDefault(require("@ampproject/remapping"));
+const core_1 = require("@babel/core");
+const node_assert_1 = __importDefault(require("node:assert"));
+const node_worker_threads_1 = require("node:worker_threads");
+const error_1 = require("../../utils/error");
+const load_esm_1 = require("../../utils/load-esm");
+// Extract the application files and common options used for inline requests from the Worker context
+// TODO: Evaluate overall performance difference of passing translations here as well
+const { files, missingTranslation, shouldOptimize } = (node_worker_threads_1.workerData || {});
+/**
+ * Inlines the provided locale and translation into a JavaScript file that contains `$localize` usage.
+ * This function is the main entry for the Worker's action that is called by the worker pool.
+ *
+ * @param request An InlineRequest object representing the options for inlining
+ * @returns An array containing the inlined file and optional map content.
+ */
+async function inlineLocale(request) {
+    const data = files.get(request.filename);
+    (0, node_assert_1.default)(data !== undefined, `Invalid inline request for file '${request.filename}'.`);
+    const code = await data.text();
+    const map = await files.get(request.filename + '.map')?.text();
+    const result = await transformWithBabel(code, map && JSON.parse(map), request);
+    return {
+        file: request.filename,
+        code: result.code,
+        map: result.map,
+        messages: result.diagnostics.messages,
+    };
+}
+exports.default = inlineLocale;
+/**
+ * Cached instance of the `@angular/localize/tools` module.
+ * This is used to remove the need to repeatedly import the module per file translation.
+ */
+let localizeToolsModule;
+/**
+ * Attempts to load the `@angular/localize/tools` module containing the functionality to
+ * perform the file translations.
+ * This module must be dynamically loaded as it is an ESM module and this file is CommonJS.
+ */
+async function loadLocalizeTools() {
+    // Load ESM `@angular/localize/tools` using the TypeScript dynamic import workaround.
+    // Once TypeScript provides support for keeping the dynamic import this workaround can be
+    // changed to a direct dynamic import.
+    localizeToolsModule ??= await (0, load_esm_1.loadEsmModule)('@angular/localize/tools');
+    return localizeToolsModule;
+}
+/**
+ * Creates the needed Babel plugins to inline a given locale and translation for a JavaScript file.
+ * @param locale A string containing the locale specifier to use.
+ * @param translation A object record containing locale specific messages to use.
+ * @returns An array of Babel plugins.
+ */
+async function createI18nPlugins(locale, translation) {
+    const { Diagnostics, makeEs2015TranslatePlugin } = await loadLocalizeTools();
+    const plugins = [];
+    const diagnostics = new Diagnostics();
+    plugins.push(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    makeEs2015TranslatePlugin(diagnostics, (translation || {}), {
+        missingTranslation: translation === undefined ? 'ignore' : missingTranslation,
+    }));
+    // Create a plugin to replace the locale specifier constant inject by the build system with the actual specifier
+    plugins.push({
+        visitor: {
+            StringLiteral(path) {
+                if (path.node.value === '___NG_LOCALE_INSERT___') {
+                    path.replaceWith(core_1.types.stringLiteral(locale));
+                }
+            },
+        },
+    });
+    return { diagnostics, plugins };
+}
+/**
+ * Transforms a JavaScript file using Babel to inline the request locale and translation.
+ * @param code A string containing the JavaScript code to transform.
+ * @param map A sourcemap object for the provided JavaScript code.
+ * @param options The inline request options to use.
+ * @returns An object containing the code, map, and diagnostics from the transformation.
+ */
+async function transformWithBabel(code, map, options) {
+    let ast;
+    try {
+        ast = (0, core_1.parseSync)(code, {
+            babelrc: false,
+            configFile: false,
+            sourceType: 'unambiguous',
+            filename: options.filename,
+        });
+    }
+    catch (error) {
+        (0, error_1.assertIsError)(error);
+        // Make the error more readable.
+        // Same errors will contain the full content of the file as the error message
+        // Which makes it hard to find the actual error message.
+        const index = error.message.indexOf(')\n');
+        const msg = index !== -1 ? error.message.slice(0, index + 1) : error.message;
+        throw new Error(`${msg}\nAn error occurred inlining file "${options.filename}"`);
+    }
+    if (!ast) {
+        throw new Error(`Unknown error occurred inlining file "${options.filename}"`);
+    }
+    const { diagnostics, plugins } = await createI18nPlugins(options.locale, options.translation);
+    const transformResult = await (0, core_1.transformFromAstAsync)(ast, code, {
+        filename: options.filename,
+        // false is a valid value but not included in the type definition
+        inputSourceMap: false,
+        sourceMaps: !!map,
+        compact: shouldOptimize,
+        configFile: false,
+        babelrc: false,
+        browserslistConfigFile: false,
+        plugins,
+    });
+    if (!transformResult || !transformResult.code) {
+        throw new Error(`Unknown error occurred processing bundle for "${options.filename}".`);
+    }
+    let outputMap;
+    if (map && transformResult.map) {
+        outputMap = (0, remapping_1.default)([transformResult.map, map], () => null);
+    }
+    return { code: transformResult.code, map: outputMap && JSON.stringify(outputMap), diagnostics };
+}

package/src/tools/esbuild/i18n-inliner.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @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 { BuildOutputFile } from './bundler-context';
+/**
+ * Inlining options that should apply to all transformed code.
+ */
+export interface I18nInlinerOptions {
+    missingTranslation: 'error' | 'warning' | 'ignore';
+    outputFiles: BuildOutputFile[];
+    shouldOptimize?: boolean;
+}
+/**
+ * A class that performs i18n translation inlining of JavaScript code.
+ * A worker pool is used to distribute the transformation actions and allow
+ * parallel processing. Inlining is only performed on code that contains the
+ * localize function (`$localize`).
+ */
+export declare class I18nInliner {
+    #private;
+    constructor(options: I18nInlinerOptions, maxThreads?: number);
+    /**
+     * Performs inlining of translations for the provided locale and translations. The files that
+     * are processed originate from the files passed to the class constructor and filter by presence
+     * of the localize function keyword.
+     * @param locale The string representing the locale to inline.
+     * @param translation The translation messages to use when inlining.
+     * @returns A promise that resolves to an array of OutputFiles representing a translated result.
+     */
+    inlineForLocale(locale: string, translation: Record<string, unknown> | undefined): Promise<{
+        outputFiles: BuildOutputFile[];
+        errors: string[];
+        warnings: string[];
+    }>;
+    /**
+     * Stops all active transformation tasks and shuts down all workers.
+     * @returns A void promise that resolves when closing is complete.
+     */
+    close(): Promise<void>;
+}

package/src/tools/esbuild/i18n-inliner.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * @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
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.I18nInliner = void 0;
+const node_assert_1 = __importDefault(require("node:assert"));
+const piscina_1 = __importDefault(require("piscina"));
+const bundler_context_1 = require("./bundler-context");
+const utils_1 = require("./utils");
+/**
+ * A keyword used to indicate if a JavaScript file may require inlining of translations.
+ * This keyword is used to avoid processing files that would not otherwise need i18n processing.
+ */
+const LOCALIZE_KEYWORD = '$localize';
+/**
+ * A class that performs i18n translation inlining of JavaScript code.
+ * A worker pool is used to distribute the transformation actions and allow
+ * parallel processing. Inlining is only performed on code that contains the
+ * localize function (`$localize`).
+ */
+class I18nInliner {
+    #workerPool;
+    #localizeFiles;
+    #unmodifiedFiles;
+    #fileToType = new Map();
+    constructor(options, maxThreads) {
+        this.#unmodifiedFiles = [];
+        const files = new Map();
+        const pendingMaps = [];
+        for (const file of options.outputFiles) {
+            if (file.type === bundler_context_1.BuildOutputFileType.Root) {
+                // Skip stats and similar files.
+                continue;
+            }
+            this.#fileToType.set(file.path, file.type);
+            if (file.path.endsWith('.js') || file.path.endsWith('.mjs')) {
+                // Check if localizations are present
+                const contentBuffer = Buffer.isBuffer(file.contents)
+                    ? file.contents
+                    : Buffer.from(file.contents.buffer, file.contents.byteOffset, file.contents.byteLength);
+                const hasLocalize = contentBuffer.includes(LOCALIZE_KEYWORD);
+                if (hasLocalize) {
+                    // A Blob is an immutable data structure that allows sharing the data between workers
+                    // without copying until the data is actually used within a Worker. This is useful here
+                    // since each file may not actually be processed in each Worker and the Blob avoids
+                    // unneeded repeat copying of potentially large JavaScript files.
+                    files.set(file.path, new Blob([file.contents]));
+                    continue;
+                }
+            }
+            else if (file.path.endsWith('.js.map')) {
+                // The related JS file may not have been checked yet. To ensure that map files are not
+                // missed, store any pending map files and check them after all output files.
+                pendingMaps.push(file);
+                continue;
+            }
+            this.#unmodifiedFiles.push(file);
+        }
+        // Check if any pending map files should be processed by checking if the parent JS file is present
+        for (const file of pendingMaps) {
+            if (files.has(file.path.slice(0, -4))) {
+                files.set(file.path, new Blob([file.contents]));
+            }
+            else {
+                this.#unmodifiedFiles.push(file);
+            }
+        }
+        this.#localizeFiles = files;
+        this.#workerPool = new piscina_1.default({
+            filename: require.resolve('./i18n-inliner-worker'),
+            maxThreads,
+            // Extract options to ensure only the named options are serialized and sent to the worker
+            workerData: {
+                missingTranslation: options.missingTranslation,
+                shouldOptimize: options.shouldOptimize,
+                files,
+            },
+            recordTiming: false,
+        });
+    }
+    /**
+     * Performs inlining of translations for the provided locale and translations. The files that
+     * are processed originate from the files passed to the class constructor and filter by presence
+     * of the localize function keyword.
+     * @param locale The string representing the locale to inline.
+     * @param translation The translation messages to use when inlining.
+     * @returns A promise that resolves to an array of OutputFiles representing a translated result.
+     */
+    async inlineForLocale(locale, translation) {
+        // Request inlining for each file that contains localize calls
+        const requests = [];
+        for (const filename of this.#localizeFiles.keys()) {
+            if (filename.endsWith('.map')) {
+                continue;
+            }
+            const fileRequest = this.#workerPool.run({
+                filename,
+                locale,
+                translation,
+            });
+            requests.push(fileRequest);
+        }
+        // Wait for all file requests to complete
+        const rawResults = await Promise.all(requests);
+        // Convert raw results to output file objects and include all unmodified files
+        const errors = [];
+        const warnings = [];
+        const outputFiles = [
+            ...rawResults.flatMap(({ file, code, map, messages }) => {
+                const type = this.#fileToType.get(file);
+                (0, node_assert_1.default)(type !== undefined, 'localized file should always have a type' + file);
+                const resultFiles = [(0, utils_1.createOutputFileFromText)(file, code, type)];
+                if (map) {
+                    resultFiles.push((0, utils_1.createOutputFileFromText)(file + '.map', map, type));
+                }
+                for (const message of messages) {
+                    if (message.type === 'error') {
+                        errors.push(message.message);
+                    }
+                    else {
+                        warnings.push(message.message);
+                    }
+                }
+                return resultFiles;
+            }),
+            ...this.#unmodifiedFiles.map((file) => file.clone()),
+        ];
+        return {
+            outputFiles,
+            errors,
+            warnings,
+        };
+    }
+    /**
+     * Stops all active transformation tasks and shuts down all workers.
+     * @returns A void promise that resolves when closing is complete.
+     */
+    close() {
+        return this.#workerPool.destroy();
+    }
+}
+exports.I18nInliner = I18nInliner;

package/src/tools/esbuild/i18n-locale-plugin.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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 { Plugin } from 'esbuild';
+/**
+ * The internal namespace used by generated locale import statements and Angular locale data plugin.
+ */
+export declare const LOCALE_DATA_NAMESPACE = "angular:locale/data";
+/**
+ * The base module location used to search for locale specific data.
+ */
+export declare const LOCALE_DATA_BASE_MODULE = "@angular/common/locales/global";
+/**
+ * Creates an esbuild plugin that resolves Angular locale data files from `@angular/common`.
+ *
+ * @returns An esbuild plugin.
+ */
+export declare function createAngularLocaleDataPlugin(): Plugin;

package/src/tools/esbuild/i18n-locale-plugin.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * @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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAngularLocaleDataPlugin = exports.LOCALE_DATA_BASE_MODULE = exports.LOCALE_DATA_NAMESPACE = void 0;
+/**
+ * The internal namespace used by generated locale import statements and Angular locale data plugin.
+ */
+exports.LOCALE_DATA_NAMESPACE = 'angular:locale/data';
+/**
+ * The base module location used to search for locale specific data.
+ */
+exports.LOCALE_DATA_BASE_MODULE = '@angular/common/locales/global';
+/**
+ * Creates an esbuild plugin that resolves Angular locale data files from `@angular/common`.
+ *
+ * @returns An esbuild plugin.
+ */
+function createAngularLocaleDataPlugin() {
+    return {
+        name: 'angular-locale-data',
+        setup(build) {
+            // If packages are configured to be external then leave the original angular locale import path.
+            // This happens when using the development server with caching enabled to allow Vite prebundling to work.
+            // There currently is no option on the esbuild resolve function to resolve while disabling the option. To
+            // workaround the inability to resolve the full locale location here, the Vite dev server prebundling also
+            // contains a plugin to allow the locales to be correctly resolved when prebundling.
+            // NOTE: If esbuild eventually allows controlling the external package options in a build.resolve call, this
+            //       workaround can be removed.
+            if (build.initialOptions.packages === 'external') {
+                return;
+            }
+            build.onResolve({ filter: /^angular:locale\/data:/ }, async ({ path }) => {
+                // Extract the locale from the path
+                const rawLocaleTag = path.split(':', 3)[2];
+                // Extract and normalize the base name of the raw locale tag
+                let partialLocaleTag;
+                try {
+                    const locale = new Intl.Locale(rawLocaleTag);
+                    partialLocaleTag = locale.baseName;
+                }
+                catch {
+                    return {
+                        path: rawLocaleTag,
+                        namespace: exports.LOCALE_DATA_NAMESPACE,
+                        errors: [
+                            {
+                                text: `Invalid or unsupported locale provided in configuration: "${rawLocaleTag}"`,
+                            },
+                        ],
+                    };
+                }
+                let exact = true;
+                while (partialLocaleTag) {
+                    // Angular embeds the `en`/`en-US` locale into the framework and it does not need to be included again here.
+                    // The onLoad hook below for the locale data namespace has an `empty` loader that will prevent inclusion.
+                    // Angular does not contain exact locale data for `en-US` but `en` is equivalent.
+                    if (partialLocaleTag === 'en' || partialLocaleTag === 'en-US') {
+                        return {
+                            path: rawLocaleTag,
+                            namespace: exports.LOCALE_DATA_NAMESPACE,
+                        };
+                    }
+                    // Attempt to resolve the locale tag data within the Angular base module location
+                    const potentialPath = `${exports.LOCALE_DATA_BASE_MODULE}/${partialLocaleTag}`;
+                    const result = await build.resolve(potentialPath, {
+                        kind: 'import-statement',
+                        resolveDir: build.initialOptions.absWorkingDir,
+                    });
+                    if (result.path) {
+                        if (exact) {
+                            return result;
+                        }
+                        else {
+                            return {
+                                ...result,
+                                warnings: [
+                                    ...result.warnings,
+                                    {
+                                        location: null,
+                                        text: `Locale data for '${rawLocaleTag}' cannot be found. Using locale data for '${partialLocaleTag}'.`,
+                                    },
+                                ],
+                            };
+                        }
+                    }
+                    // Remove the last subtag and try again with a less specific locale.
+                    // Usually the match is exact so the string splitting here is not done until actually needed after the exact
+                    // match fails to resolve.
+                    const parts = partialLocaleTag.split('-');
+                    partialLocaleTag = parts.slice(0, -1).join('-');
+                    exact = false;
+                }
+                // Not found so issue a warning and use an empty loader. Framework built-in `en-US` data will be used.
+                // This retains existing behavior as in the Webpack-based builder.
+                return {
+                    path: rawLocaleTag,
+                    namespace: exports.LOCALE_DATA_NAMESPACE,
+                    warnings: [
+                        {
+                            location: null,
+                            text: `Locale data for '${rawLocaleTag}' cannot be found. No locale data will be included for this locale.`,
+                        },
+                    ],
+                };
+            });
+            // Locales that cannot be found will be loaded as empty content with a warning from the resolve step
+            build.onLoad({ filter: /./, namespace: exports.LOCALE_DATA_NAMESPACE }, () => ({
+                contents: '',
+                loader: 'empty',
+            }));
+        },
+    };
+}
+exports.createAngularLocaleDataPlugin = createAngularLocaleDataPlugin;

package/src/tools/esbuild/index-html-generator.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @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 { NormalizedApplicationBuildOptions } from '../../builders/application/options';
+import { BuildOutputFile, InitialFileRecord } from './bundler-context';
+export declare function generateIndexHtml(initialFiles: Map<string, InitialFileRecord>, outputFiles: BuildOutputFile[], buildOptions: NormalizedApplicationBuildOptions, lang?: string): Promise<{
+    csrContent: string;
+    ssrContent?: string;
+    warnings: string[];
+    errors: string[];
+}>;