feat(vite-plugin-angular): introduce support for Angular Compilation API

Author: brandonroberts

apps/analog-app/tsconfig.app.json

@@ -6,7 +6,11 @@
     "target": "ES2022",
     "useDefineForClassFields": false
   },
-  "files": ["src/main.ts", "src/main.server.ts"],
+  "files": [
+    "src/main.ts",
+    "src/main.server.ts",
+    "src/environments/environment.prod.ts"
+  ],
   "include": [
     "src/**/*.d.ts",
     "src/app/pages/**/*.page.ts",

apps/analog-app/vite.config.ts

@@ -72,8 +72,11 @@ export default defineConfig(({ mode }) => {
         },
         vite: {
           inlineStylesExtension: 'scss',
+          experimental: {
+            useAngularCompilationAPI: true,
+          },
         },
-        liveReload: true,
+        liveReload: false,
         nitro: {
           routeRules: {
             '/cart/**': {

libs/top-bar/vite.config.ts

@@ -7,7 +7,7 @@ import angular from '@analogjs/vite-plugin-angular';
 export default defineConfig(({ mode }) => {
   return {
     root: __dirname,
-    plugins: [angular()],
+    plugins: [angular({ experimental: { useAngularCompilationAPI: true } })],
     test: {
       reporters: ['default'],
       globals: true,

packages/vite-plugin-angular/src/lib/angular-pending-tasks.plugin.ts

@@ -1,6 +1,6 @@
 import { Plugin } from 'vite';
 
-import { angularMajor, angularMinor, angularPatch } from './utils/devkit.js';
+import { angularFullVersion } from './utils/devkit.js';
 
 /**
  * This plugin is a workaround for the ɵPendingTasks symbol being renamed
@@ -13,14 +13,7 @@ export function pendingTasksPlugin(): Plugin {
   return {
     name: 'analogjs-pending-tasks-plugin',
     transform(code, id) {
-      const padVersion = (version: number) => String(version).padStart(2, '0');
-
-      if (
-        Number(
-          `${angularMajor}${padVersion(angularMinor)}${padVersion(angularPatch)}`,
-        ) < 190004 &&
-        id.includes('analogjs-content.mjs')
-      ) {
+      if (angularFullVersion < 190004 && id.includes('analogjs-content.mjs')) {
         return {
           code: code.replace('ɵPendingTasksInternal', 'ɵPendingTasks'),
         };

packages/vite-plugin-angular/src/lib/angular-vite-plugin.ts

@@ -12,6 +12,7 @@ import {
 import * as compilerCli from '@angular/compiler-cli';
 import { createRequire } from 'node:module';
 import * as ts from 'typescript';
+import { type createAngularCompilation as createAngularCompilationType } from '@angular/build/private';
 
 import * as ngCompiler from '@angular/compiler';
 import {
@@ -40,9 +41,10 @@ import {
 
 import { angularVitestPlugins } from './angular-vitest-plugin.js';
 import {
-  angularMajor,
+  createAngularCompilation,
   createJitResourceTransformer,
   SourceFileCache,
+  angularFullVersion,
 } from './utils/devkit.js';
 
 const require = createRequire(import.meta.url);
@@ -58,6 +60,15 @@ import {
   replaceFiles,
 } from './plugins/file-replacements.plugin.js';
 import { routerPlugin } from './router-plugin.js';
+import { createHash } from 'node:crypto';
+
+export enum DiagnosticModes {
+  None = 0,
+  Option = 1 << 0,
+  Syntactic = 1 << 1,
+  Semantic = 1 << 2,
+  All = Option | Syntactic | Semantic,
+}
 
 export interface PluginOptions {
   tsconfig?: string | (() => string);
@@ -80,6 +91,9 @@ export interface PluginOptions {
   liveReload?: boolean;
   disableTypeChecking?: boolean;
   fileReplacements?: FileReplacement[];
+  experimental?: {
+    useAngularCompilationAPI?: boolean;
+  };
 }
 
 /**
@@ -120,6 +134,8 @@ export function angular(options?: PluginOptions): Plugin[] {
     liveReload: options?.liveReload ?? false,
     disableTypeChecking: options?.disableTypeChecking ?? true,
     fileReplacements: options?.fileReplacements ?? [],
+    useAngularCompilationAPI:
+      options?.experimental?.useAngularCompilationAPI ?? false,
   };
 
   let resolvedConfig: ResolvedConfig;
@@ -157,14 +173,38 @@ export function angular(options?: PluginOptions): Plugin[] {
   };
   let initialCompilation = false;
   const declarationFiles: DeclarationFile[] = [];
+  let compilation: Awaited<ReturnType<typeof createAngularCompilationType>>;
 
   function angularPlugin(): Plugin {
     let isProd = false;
 
-    if (angularMajor < 19 || isTest) {
+    if (angularFullVersion < 190000 || isTest) {
       pluginOptions.liveReload = false;
     }
 
+    if (pluginOptions.useAngularCompilationAPI) {
+      if (angularFullVersion < 200100) {
+        pluginOptions.useAngularCompilationAPI = false;
+        console.warn(
+          '[@analogjs/vite-plugin-angular]: The Angular Compilation API is only available with Angular v20.1 and later',
+        );
+      }
+
+      if (pluginOptions.liveReload) {
+        pluginOptions.liveReload = false;
+        console.warn(
+          '[@analogjs-vite-plugin-angular]: Live reload is currently not compatible with the Angular Compilation API option',
+        );
+      }
+
+      if (pluginOptions.fileReplacements) {
+        pluginOptions.fileReplacements = [];
+        console.warn(
+          '[@analogjs-vite-plugin-angular]: File replacements are currently not compatible with the Angular Compilation API option',
+        );
+      }
+    }
+
     return {
       name: '@analogjs/vite-plugin-angular',
       async config(config, { command }) {
@@ -226,6 +266,11 @@ export function angular(options?: PluginOptions): Plugin[] {
       configResolved(config) {
         resolvedConfig = config;
 
+        if (pluginOptions.useAngularCompilationAPI) {
+          externalComponentStyles = new Map();
+          inlineComponentStyles = new Map();
+        }
+
         // resolve the tsconfig path after config is fully resolved
         if (tsConfigResolutionContext) {
           const tsconfigValue = pluginOptions.tsconfigGetter();
@@ -672,7 +717,113 @@ export function angular(options?: PluginOptions): Plugin[] {
     return resolvedPath;
   }
 
+  async function performAngularCompilation(config: ResolvedConfig) {
+    compilation = await (
+      createAngularCompilation as typeof createAngularCompilationType
+    )(!!pluginOptions.jit, false);
+    const compilationResult = await compilation.initialize(
+      resolvedTsConfigPath,
+      {
+        async transformStylesheet(
+          data,
+          containingFile,
+          resourceFile,
+          order,
+          className,
+        ) {
+          if (pluginOptions.liveReload) {
+            const id = createHash('sha256')
+              .update(containingFile)
+              .update(className as string)
+              .update(String(order))
+              .update(data)
+              .digest('hex');
+            const filename = id + '.' + pluginOptions.inlineStylesExtension;
+            inlineComponentStyles!.set(filename, data);
+            return filename;
+          }
+
+          const filename =
+            resourceFile ??
+            containingFile.replace('.ts', `.${options?.inlineStylesExtension}`);
+
+          let stylesheetResult;
+
+          try {
+            stylesheetResult = await preprocessCSS(
+              data,
+              `${filename}?direct`,
+              resolvedConfig,
+            );
+          } catch (e) {
+            console.error(`${e}`);
+          }
+
+          return stylesheetResult?.code || '';
+        },
+        processWebWorker(workerFile, containingFile) {
+          return '';
+        },
+      },
+      (tsCompilerOptions) => {
+        if (pluginOptions.liveReload && watchMode) {
+          tsCompilerOptions['_enableHmr'] = true;
+          tsCompilerOptions['externalRuntimeStyles'] = true;
+          // Workaround for https://github.com/angular/angular/issues/59310
+          // Force extra instructions to be generated for HMR w/defer
+          tsCompilerOptions['supportTestBed'] = true;
+        }
+
+        if (tsCompilerOptions.compilationMode === 'partial') {
+          // These options can't be false in partial mode
+          tsCompilerOptions['supportTestBed'] = true;
+          tsCompilerOptions['supportJitMode'] = true;
+        }
+
+        if (!isTest && config.build?.lib) {
+          tsCompilerOptions['declaration'] = true;
+          tsCompilerOptions['declarationMap'] = watchMode;
+          tsCompilerOptions['inlineSources'] = true;
+        }
+
+        if (isTest) {
+          // Allow `TestBed.overrideXXX()` APIs.
+          tsCompilerOptions['supportTestBed'] = true;
+        }
+
+        return tsCompilerOptions;
+      },
+    );
+
+    compilationResult.externalStylesheets?.forEach((value, key) => {
+      externalComponentStyles?.set(`${value}.css`, key);
+    });
+
+    const diagnostics = await compilation.diagnoseFiles(
+      pluginOptions.disableTypeChecking
+        ? DiagnosticModes.All & ~DiagnosticModes.Semantic
+        : DiagnosticModes.All,
+    );
+
+    const errors = diagnostics.errors?.length ? diagnostics.errors : [];
+    const warnings = diagnostics.warnings?.length ? diagnostics.warnings : [];
+
+    for (const file of await compilation.emitAffectedFiles()) {
+      outputFiles.set(file.filename, {
+        content: file.contents,
+        dependencies: [],
+        errors: errors.map((error) => error.text || ''),
+        warnings: warnings.map((warning) => warning.text || ''),
+      });
+    }
+  }
+
   async function performCompilation(config: ResolvedConfig, ids?: string[]) {
+    if (pluginOptions.useAngularCompilationAPI) {
+      await performAngularCompilation(config);
+      return { host: {} };
+    }
+
     const isProd = config.mode === 'production';
     const includeFiles = findIncludes();
 

packages/vite-plugin-angular/src/lib/utils/devkit.ts

@@ -8,9 +8,14 @@ const require = createRequire(import.meta.url);
 const angularMajor = Number(VERSION.major);
 const angularMinor = Number(VERSION.minor);
 const angularPatch = Number(VERSION.patch);
+const padVersion = (version: number) => String(version).padStart(2, '0');
+const angularFullVersion = Number(
+  `${angularMajor}${padVersion(angularMinor)}${padVersion(angularPatch)}`,
+);
 let sourceFileCache: any;
 let cjt: Function;
 let jt: any;
+let createAngularCompilation: Function;
 
 if (angularMajor < 17) {
   throw new Error('AnalogJS is not compatible with Angular v16 and lower');
@@ -39,11 +44,13 @@ if (angularMajor < 17) {
     createJitResourceTransformer,
     JavaScriptTransformer,
     SourceFileCache,
+    createAngularCompilation: createAngularCompilationFn,
   } = require('@angular/build/private');
 
   sourceFileCache = SourceFileCache;
   cjt = createJitResourceTransformer;
   jt = JavaScriptTransformer;
+  createAngularCompilation = createAngularCompilationFn;
 }
 
 export {
@@ -54,4 +61,6 @@ export {
   angularMajor,
   angularMinor,
   angularPatch,
+  createAngularCompilation,
+  angularFullVersion,
 };