feat(@angular-devkit/build-angular): provide partial custom postcss configuration support

The `browser` builder now supports providing a custom postcss configuration
similar to the functionality available in the `@angular/build:application`
builder. A postcss configuration file named either `postcss.config.json` or
`.postcssrc.json` will be discovered in order from the project root or
workspace root. Only plugins can be configured via the file. All other
fields will be ignored. Additionally the plugins will be placed after
any internal build system plugins but before `autoprefixer`.
When using a custom postcss configuration, the automatic tailwind integration
will be disabled. The Tailwind postcss plugin should be added to the configuration
file in this scenario.

Co-Authored-By: Jan Martin <jankrems@google.com>

Author: clydin

packages/angular/build/src/private.ts

@@ -84,3 +84,8 @@ export { type BundleStats, generateBuildStatsTable } from './utils/stats-table';
 export { getSupportedBrowsers } from './utils/supported-browsers';
 export { assertCompatibleAngularVersion } from './utils/version';
 export { findTests, getTestEntrypoints } from './builders/karma/find-tests';
+export {
+  findTailwindConfiguration,
+  generateSearchDirectories,
+  loadPostcssConfiguration,
+} from './utils/postcss-configuration';

packages/angular_devkit/build_angular/src/builders/browser/tests/behavior/postcss_config_spec.ts

@@ -0,0 +1,57 @@
+/**
+ * @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.dev/license
+ */
+
+import { buildWebpackBrowser } from '../../index';
+import { BASE_OPTIONS, BROWSER_BUILDER_INFO, describeBuilder } from '../setup';
+
+describeBuilder(buildWebpackBrowser, BROWSER_BUILDER_INFO, (harness) => {
+  describe('Behavior: "Postcss config file"', () => {
+    it('applies plugins from config file if one is present', async () => {
+      // See:
+      // https://github.com/postcss/postcss-plugin-boilerplate/blob/main/template/index.t.js
+      await harness.writeFile(
+        'node_modules/my-postcss-plugin/index.cjs',
+        `module.exports = (opts = {}) => {
+  return {
+    postcssPlugin: 'my-postcss-plugin',
+
+    Root(root, postcss) {
+      const newRule = new postcss.Rule({
+        selector: '.my-postcss-plugin::before',
+      });
+      newRule.append({ text: 'content: "from applied plugin";' });
+      root.append(newRule);
+    },
+  };
+};
+
+module.exports.postcss = true;
+`,
+      );
+
+      await harness.writeFile(
+        'postcss.config.json',
+        JSON.stringify({
+          plugins: {
+            'my-postcss-plugin/index.cjs': {},
+          },
+        }),
+      );
+
+      harness.useTarget('build', {
+        ...BASE_OPTIONS,
+        styles: ['src/styles.css'],
+      });
+
+      const { result } = await harness.executeOnce();
+
+      expect(result?.success).toBe(true);
+      harness.expectFile('dist/styles.css').content.toMatch(/from applied plugin/);
+    });
+  });
+});

packages/angular_devkit/build_angular/src/tools/webpack/configs/styles.ts

@@ -6,14 +6,18 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import { SassWorkerImplementation } from '@angular/build/private';
+import {
+  SassWorkerImplementation,
+  findTailwindConfiguration,
+  generateSearchDirectories,
+  loadPostcssConfiguration,
+} from '@angular/build/private';
 import MiniCssExtractPlugin from 'mini-css-extract-plugin';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import type { FileImporter } from 'sass';
 import type { Configuration, LoaderContext, RuleSetUseItem } from 'webpack';
 import { WebpackConfigOptions } from '../../../utils/build-options';
-import { findTailwindConfigurationFile } from '../../../utils/tailwind';
 import {
   AnyComponentStyleBudgetChecker,
   PostcssCliResources,
@@ -75,25 +79,40 @@ export async function getStylesConfig(wco: WebpackConfigOptions): Promise<Config
 
   const extraPostcssPlugins: import('postcss').Plugin[] = [];
 
-  // Attempt to setup Tailwind CSS
-  // Only load Tailwind CSS plugin if configuration file was found.
-  // This acts as a guard to ensure the project actually wants to use Tailwind CSS.
-  // The package may be unknowningly present due to a third-party transitive package dependency.
-  const tailwindConfigPath = await findTailwindConfigurationFile(root, projectRoot);
-  if (tailwindConfigPath) {
-    let tailwindPackagePath;
-    try {
-      tailwindPackagePath = require.resolve('tailwindcss', { paths: [root] });
-    } catch {
-      const relativeTailwindConfigPath = path.relative(root, tailwindConfigPath);
-      logger.warn(
-        `Tailwind CSS configuration file found (${relativeTailwindConfigPath})` +
-          ` but the 'tailwindcss' package is not installed.` +
-          ` To enable Tailwind CSS, please install the 'tailwindcss' package.`,
-      );
+  const searchDirectories = await generateSearchDirectories([projectRoot, root]);
+  const postcssConfig = await loadPostcssConfiguration(searchDirectories);
+
+  if (postcssConfig) {
+    for (const [pluginName, pluginOptions] of postcssConfig.plugins) {
+      const resolvedPlugin = require.resolve(pluginName, { paths: [root] });
+      const { default: plugin } = await import(resolvedPlugin);
+      if (typeof plugin !== 'function' || plugin.postcss !== true) {
+        throw new Error(`Attempted to load invalid Postcss plugin: "${pluginName}"`);
+      }
+
+      extraPostcssPlugins.push(plugin(pluginOptions));
     }
-    if (tailwindPackagePath) {
-      extraPostcssPlugins.push(require(tailwindPackagePath)({ config: tailwindConfigPath }));
+  } else {
+    // Attempt to setup Tailwind CSS
+    // Only load Tailwind CSS plugin if configuration file was found.
+    // This acts as a guard to ensure the project actually wants to use Tailwind CSS.
+    // The package may be unknowningly present due to a third-party transitive package dependency.
+    const tailwindConfigPath = findTailwindConfiguration(searchDirectories);
+    if (tailwindConfigPath) {
+      let tailwindPackagePath;
+      try {
+        tailwindPackagePath = require.resolve('tailwindcss', { paths: [root] });
+      } catch {
+        const relativeTailwindConfigPath = path.relative(root, tailwindConfigPath);
+        logger.warn(
+          `Tailwind CSS configuration file found (${relativeTailwindConfigPath})` +
+            ` but the 'tailwindcss' package is not installed.` +
+            ` To enable Tailwind CSS, please install the 'tailwindcss' package.`,
+        );
+      }
+      if (tailwindPackagePath) {
+        extraPostcssPlugins.push(require(tailwindPackagePath)({ config: tailwindConfigPath }));
+      }
     }
   }