refactor(@angular/build): move postcss stylesheet processor to an optional peer dependency

The Postcss stylesheet processor is now an optional peer dependency of the
newly introduced `@angular/build` build system package. This change removes
the need for the package to have a direct dependency on the `postcss` package
and allows some version customization of the optional `postcss` package if needed.
Postcss plugins (including Tailwind) are still fully supported but usage will now require installing
the `postcss` package within the Angular workspace. An error with instructions to
install the package will be generated during a build if the package is not present.
This change only affects direct usage of the new `@angular/build` package.
The `@angular-devkit/build-angular` package which is currently used for all existing
projects will continue to contain and directly depend on the `postcss` package.

No changes are required for existing applications.

(cherry picked from commit 6b5c51a)

Author: clydin

packages/angular/build/package.json

@@ -50,6 +50,7 @@
     "@angular/platform-server": "^18.0.0 || ^18.0.0-next.0",
     "@angular/service-worker": "^18.0.0 || ^18.0.0-next.0",
     "less": "^4.2.0",
+    "postcss": "^8.4.0",
     "tailwindcss": "^2.0.0 || ^3.0.0",
     "typescript": ">=5.4 <5.5"
   },
@@ -66,6 +67,9 @@
     "less": {
       "optional": true
     },
+    "postcss": {
+      "optional": true
+    },
     "tailwindcss": {
       "optional": true
     }

packages/angular/build/src/tools/esbuild/stylesheets/stylesheet-plugin-factory.ts

@@ -14,6 +14,11 @@ import { extname } from 'node:path';
 import type { PostcssConfiguration } from '../../../utils/postcss-configuration';
 import { LoadResultCache, createCachedLoad } from '../load-result-cache';
 
+/**
+ * Convenience type for a postcss processor.
+ */
+type PostcssProcessor = import('postcss').Processor;
+
 /**
  * The lazy-loaded instance of the postcss stylesheet postprocessor.
  * It is only imported and initialized if postcss is needed.
@@ -88,10 +93,10 @@ export interface StylesheetLanguage {
 /**
  * Cached postcss instances that can be re-used between various StylesheetPluginFactory instances.
  */
-const postcssProcessor = new Map<string, WeakRef<import('postcss').Processor>>();
+const postcssProcessors = new Map<string, WeakRef<PostcssProcessor>>();
 
 export class StylesheetPluginFactory {
-  private postcssProcessor?: import('postcss').Processor;
+  private postcssProcessor?: PostcssProcessor;
 
   constructor(
     private readonly options: StylesheetPluginOptions,
@@ -121,7 +126,7 @@ export class StylesheetPluginFactory {
       if (options.postcssConfiguration) {
         const postCssInstanceKey = JSON.stringify(options.postcssConfiguration);
 
-        this.postcssProcessor = postcssProcessor.get(postCssInstanceKey)?.deref();
+        this.postcssProcessor = postcssProcessors.get(postCssInstanceKey)?.deref();
 
         if (!this.postcssProcessor) {
           postcss ??= (await import('postcss')).default;
@@ -135,18 +140,18 @@ export class StylesheetPluginFactory {
             this.postcssProcessor.use(plugin(pluginOptions));
           }
 
-          postcssProcessor.set(postCssInstanceKey, new WeakRef(this.postcssProcessor));
+          postcssProcessors.set(postCssInstanceKey, new WeakRef(this.postcssProcessor));
         }
       } else if (options.tailwindConfiguration) {
         const { package: tailwindPackage, file: config } = options.tailwindConfiguration;
         const postCssInstanceKey = tailwindPackage + ':' + config;
-        this.postcssProcessor = postcssProcessor.get(postCssInstanceKey)?.deref();
+        this.postcssProcessor = postcssProcessors.get(postCssInstanceKey)?.deref();
 
         if (!this.postcssProcessor) {
           postcss ??= (await import('postcss')).default;
           const tailwind = await import(tailwindPackage);
           this.postcssProcessor = postcss().use(tailwind.default({ config }));
-          postcssProcessor.set(postCssInstanceKey, new WeakRef(this.postcssProcessor));
+          postcssProcessors.set(postCssInstanceKey, new WeakRef(this.postcssProcessor));
         }
       }
 
@@ -157,7 +162,28 @@ export class StylesheetPluginFactory {
       name: 'angular-' + language.name,
       async setup(build) {
         // Setup postcss if needed
-        const postcssProcessor = await setupPostcss();
+        let postcssProcessor: PostcssProcessor | undefined;
+        build.onStart(async () => {
+          try {
+            postcssProcessor = await setupPostcss();
+          } catch {
+            return {
+              errors: [
+                {
+                  text: 'Unable to load the "postcss" stylesheet processor.',
+                  location: null,
+                  notes: [
+                    {
+                      text:
+                        'Ensure that the "postcss" Node.js package is installed within the project. ' +
+                        "If not present, installation via the project's package manager should resolve the error.",
+                    },
+                  ],
+                },
+              ],
+            };
+          }
+        });
 
         // Add a load callback to support inline Component styles
         build.onLoad(
@@ -212,7 +238,7 @@ async function processStylesheet(
   format: string,
   options: StylesheetPluginOptions,
   build: PluginBuild,
-  postcssProcessor: import('postcss').Processor | undefined,
+  postcssProcessor: PostcssProcessor | undefined,
 ) {
   let result: OnLoadResult;