feat(@angular-devkit/build-angular): allow configuring loaders for cu…

…stom file extensions in application builder

When using the `application` builder, a new `loader` option is now available for use.
The option allows a project to define the type of loader to use with a specified file extension.
A file with the defined extension can then used within the application code via an import statement
or dynamic import expression, for instance.
The available loaders that can be used are:
* `text` - inlines the content as a string
* `binary` - inlines the content as a Uint8Array
* `file` - emits the file and provides the runtime location of the file
* `empty` - considers the content to be empty and will not include it in bundles

The loader option is an object-based option with the keys used to define the file extension and the values used
to define the loader type.

An example to inline the content of SVG files into the bundled application would be as follows:
```
loader: {
    ".svg": "text"
}
```
An SVG file can then be imported:
```
import contents from './some-file.svg';
```
Additionally, TypeScript needs to be aware of the module type for the import to prevent type-checking
errors during the build. This can be accomplished with an additional type definition file within the
application source code (`src/types.d.ts`, for example) with the following or similar content:
```
declare module "*.svg" {
  const content: string;
  export default content;
}
```
The default project configuration is already setup to use any type definition files present in the project
source directories. If the TypeScript configuration for the project has been altered, the tsconfig may
need to be adjusted to reference this newly added type definition file.

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

@@ -37,6 +37,9 @@ export interface ApplicationBuilderOptions {
     i18nMissingTranslation?: I18NTranslation_2;
     index: IndexUnion_2;
     inlineStyleLanguage?: InlineStyleLanguage_2;
+    loader?: {
+        [key: string]: any;
+    };
     localize?: Localize_2;
     namedChunks?: boolean;
     optimization?: OptimizationUnion_2;

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

@@ -143,6 +143,20 @@ export async function normalizeOptions(
     }
   }
 
+  let loaderExtensions: Record<string, 'text' | 'binary' | 'file'> | undefined;
+  if (options.loader) {
+    for (const [extension, value] of Object.entries(options.loader)) {
+      if (extension[0] !== '.' || /\.[cm]?[jt]sx?$/.test(extension)) {
+        continue;
+      }
+      if (value !== 'text' && value !== 'binary' && value !== 'file' && value !== 'empty') {
+        continue;
+      }
+      loaderExtensions ??= {};
+      loaderExtensions[extension] = value;
+    }
+  }
+
   const globalStyles: { name: string; files: string[]; initial: boolean }[] = [];
   if (options.styles?.length) {
     const { entryPoints: stylesheetEntrypoints, noInjectNames } = normalizeGlobalStyles(
@@ -307,6 +321,7 @@ export async function normalizeOptions(
     budgets: budgets?.length ? budgets : undefined,
     publicPath: deployUrl ? deployUrl : undefined,
     plugins: plugins?.length ? plugins : undefined,
+    loaderExtensions,
   };
 }
 

packages/angular_devkit/build_angular/src/builders/application/schema.json

@@ -199,6 +199,13 @@
         }
       ]
     },
+    "loader": {
+      "description": "Defines the type of loader to use with a specified file extension when used with a JavaScript `import`. `text` inlines the content as a string; `binary` inlines the content as a Uint8Array; `file` emits the file and provides the runtime location of the file; `empty` considers the content to be empty and not include it in bundles.",
+      "type": "object",
+      "patternProperties": {
+        "^\\.\\S+$": { "enum": ["text", "binary", "file", "empty"] }
+      }
+    },
     "fileReplacements": {
       "description": "Replace compilation source files with other compilation source files in the build.",
       "type": "array",

packages/angular_devkit/build_angular/src/builders/application/tests/options/loader_spec.ts

@@ -0,0 +1,257 @@
+/**
+ * @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 { buildApplication } from '../../index';
+import { APPLICATION_BUILDER_INFO, BASE_OPTIONS, describeBuilder } from '../setup';
+
+describeBuilder(buildApplication, APPLICATION_BUILDER_INFO, (harness) => {
+  describe('Option: "loader"', () => {
+    it('should error for an unknown file extension', async () => {
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+      });
+
+      await harness.writeFile(
+        './src/types.d.ts',
+        'declare module "*.unknown" { const content: string; export default content; }',
+      );
+      await harness.writeFile('./src/a.unknown', 'ABC');
+      await harness.writeFile(
+        'src/main.ts',
+        'import contents from "./a.unknown";\n console.log(contents);',
+      );
+
+      const { result, logs } = await harness.executeOnce({ outputLogsOnFailure: false });
+      expect(result?.success).toBe(false);
+      expect(logs).toContain(
+        jasmine.objectContaining({
+          message: jasmine.stringMatching(
+            'No loader is configured for ".unknown" files: src/a.unknown',
+          ),
+        }),
+      );
+    });
+
+    it('should not include content for file extension set to "empty"', async () => {
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        loader: {
+          '.unknown': 'empty',
+        },
+      });
+
+      await harness.writeFile(
+        './src/types.d.ts',
+        'declare module "*.unknown" { const content: string; export default content; }',
+      );
+      await harness.writeFile('./src/a.unknown', 'ABC');
+      await harness.writeFile(
+        'src/main.ts',
+        'import contents from "./a.unknown";\n console.log(contents);',
+      );
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBe(true);
+      harness.expectFile('dist/browser/main.js').content.not.toContain('ABC');
+    });
+
+    it('should inline text content for file extension set to "text"', async () => {
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        loader: {
+          '.unknown': 'text',
+        },
+      });
+
+      await harness.writeFile(
+        './src/types.d.ts',
+        'declare module "*.unknown" { const content: string; export default content; }',
+      );
+      await harness.writeFile('./src/a.unknown', 'ABC');
+      await harness.writeFile(
+        'src/main.ts',
+        'import contents from "./a.unknown";\n console.log(contents);',
+      );
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBe(true);
+      harness.expectFile('dist/browser/main.js').content.toContain('ABC');
+    });
+
+    it('should inline binary content for file extension set to "binary"', async () => {
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        loader: {
+          '.unknown': 'binary',
+        },
+      });
+
+      await harness.writeFile(
+        './src/types.d.ts',
+        'declare module "*.unknown" { const content: Uint8Array; export default content; }',
+      );
+      await harness.writeFile('./src/a.unknown', 'ABC');
+      await harness.writeFile(
+        'src/main.ts',
+        'import contents from "./a.unknown";\n console.log(contents);',
+      );
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBe(true);
+      // Should contain the binary encoding used esbuild and not the text content
+      harness.expectFile('dist/browser/main.js').content.toContain('__toBinary("QUJD")');
+      harness.expectFile('dist/browser/main.js').content.not.toContain('ABC');
+    });
+
+    it('should emit an output file for file extension set to "file"', async () => {
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        loader: {
+          '.unknown': 'file',
+        },
+      });
+
+      await harness.writeFile(
+        './src/types.d.ts',
+        'declare module "*.unknown" { const location: string; export default location; }',
+      );
+      await harness.writeFile('./src/a.unknown', 'ABC');
+      await harness.writeFile(
+        'src/main.ts',
+        'import contents from "./a.unknown";\n console.log(contents);',
+      );
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBe(true);
+      harness.expectFile('dist/browser/main.js').content.toContain('a.unknown');
+      harness.expectFile('dist/browser/media/a.unknown').toExist();
+    });
+
+    it('should emit an output file with hashing when enabled for file extension set to "file"', async () => {
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        outputHashing: 'media' as any,
+        loader: {
+          '.unknown': 'file',
+        },
+      });
+
+      await harness.writeFile(
+        './src/types.d.ts',
+        'declare module "*.unknown" { const location: string; export default location; }',
+      );
+      await harness.writeFile('./src/a.unknown', 'ABC');
+      await harness.writeFile(
+        'src/main.ts',
+        'import contents from "./a.unknown";\n console.log(contents);',
+      );
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBe(true);
+      harness.expectFile('dist/browser/main.js').content.toContain('a.unknown');
+      expect(harness.hasFileMatch('dist/browser/media', /a-[0-9A-Z]{8}\.unknown$/)).toBeTrue();
+    });
+
+    it('should inline text content for `.txt` by default', async () => {
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        loader: undefined,
+      });
+
+      await harness.writeFile(
+        './src/types.d.ts',
+        'declare module "*.txt" { const content: string; export default content; }',
+      );
+      await harness.writeFile('./src/a.txt', 'ABC');
+      await harness.writeFile(
+        'src/main.ts',
+        'import contents from "./a.txt";\n console.log(contents);',
+      );
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBe(true);
+      harness.expectFile('dist/browser/main.js').content.toContain('ABC');
+    });
+
+    it('should inline text content for `.txt` by default when other extensions are defined', async () => {
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        loader: {
+          '.unknown': 'binary',
+        },
+      });
+
+      await harness.writeFile(
+        './src/types.d.ts',
+        'declare module "*.txt" { const content: string; export default content; }',
+      );
+      await harness.writeFile('./src/a.txt', 'ABC');
+      await harness.writeFile(
+        'src/main.ts',
+        'import contents from "./a.txt";\n console.log(contents);',
+      );
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBe(true);
+      harness.expectFile('dist/browser/main.js').content.toContain('ABC');
+    });
+
+    it('should allow overriding default `.txt` extension behavior', async () => {
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        loader: {
+          '.txt': 'file',
+        },
+      });
+
+      await harness.writeFile(
+        './src/types.d.ts',
+        'declare module "*.txt" { const location: string; export default location; }',
+      );
+      await harness.writeFile('./src/a.txt', 'ABC');
+      await harness.writeFile(
+        'src/main.ts',
+        'import contents from "./a.txt";\n console.log(contents);',
+      );
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBe(true);
+      harness.expectFile('dist/browser/main.js').content.toContain('a.txt');
+      harness.expectFile('dist/browser/media/a.txt').toExist();
+    });
+
+    // Schema validation will prevent this from happening for supported use-cases.
+    // This will only happen if used programmatically and the option value is set incorrectly.
+    it('should ignore entry if an invalid loader name is used', async () => {
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        loader: {
+          '.unknown': 'invalid',
+        },
+      });
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBe(true);
+    });
+
+    // Schema validation will prevent this from happening for supported use-cases.
+    // This will only happen if used programmatically and the option value is set incorrectly.
+    it('should ignore entry if an extension does not start with a period', async () => {
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        loader: {
+          'unknown': 'text',
+        },
+      });
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBe(true);
+    });
+  });
+});

packages/angular_devkit/build_angular/src/builders/dev-server/vite-server.ts

@@ -234,6 +234,7 @@ export async function* serveWithVite(
         !!browserOptions.ssr,
         prebundleTransformer,
         target,
+        browserOptions.loader as EsbuildLoaderOption | undefined,
         extensions?.middleware,
         transformers?.indexHtml,
       );
@@ -401,6 +402,7 @@ export async function setupServer(
   ssr: boolean,
   prebundleTransformer: JavaScriptTransformer,
   target: string[],
+  prebundleLoaderExtensions: EsbuildLoaderOption | undefined,
   extensionMiddleware?: Connect.NextHandleFunction[],
   indexHtmlTransformer?: (content: string) => Promise<string>,
 ): Promise<InlineConfig> {
@@ -481,6 +483,7 @@ export async function setupServer(
         ssr: true,
         prebundleTransformer,
         target,
+        loader: prebundleLoaderExtensions,
       }),
     },
     plugins: [
@@ -736,6 +739,7 @@ export async function setupServer(
       ssr: false,
       prebundleTransformer,
       target,
+      loader: prebundleLoaderExtensions,
     }),
   };
 
@@ -796,20 +800,24 @@ type ViteEsBuildPlugin = NonNullable<
   NonNullable<DepOptimizationConfig['esbuildOptions']>['plugins']
 >[0];
 
+type EsbuildLoaderOption = Exclude<DepOptimizationConfig['esbuildOptions'], undefined>['loader'];
+
 function getDepOptimizationConfig({
   disabled,
   exclude,
   include,
   target,
   prebundleTransformer,
   ssr,
+  loader,
 }: {
   disabled: boolean;
   exclude: string[];
   include: string[];
   target: string[];
   prebundleTransformer: JavaScriptTransformer;
   ssr: boolean;
+  loader?: EsbuildLoaderOption;
 }): DepOptimizationConfig {
   const plugins: ViteEsBuildPlugin[] = [
     {
@@ -842,6 +850,7 @@ function getDepOptimizationConfig({
       target,
       supported: getFeatureSupport(target),
       plugins,
+      loader,
     },
   };
 }

packages/angular_devkit/build_angular/src/tools/esbuild/application-code-bundle.ts

@@ -320,6 +320,7 @@ function getEsBuildCommonOptions(options: NormalizedApplicationBuildOptions): Bu
     outputNames,
     preserveSymlinks,
     jit,
+    loaderExtensions,
   } = options;
 
   // Ensure unique hashes for i18n translation changes when using post-process inlining.
@@ -367,6 +368,7 @@ function getEsBuildCommonOptions(options: NormalizedApplicationBuildOptions): Bu
       ...(optimizationOptions.scripts ? { 'ngDevMode': 'false' } : undefined),
       'ngJitMode': jit ? 'true' : 'false',
     },
+    loader: loaderExtensions,
     footer,
     publicPath: options.publicPath,
   };