feat(v2): allow extend PostCSS config

packages/docusaurus-types/src/index.d.ts

@@ -220,6 +220,7 @@ export interface Plugin<T, U = unknown> {
     isServer: boolean,
     utils: ConfigureWebpackUtils,
   ): Configuration & {mergeStrategy?: ConfigureWebpackFnMergeStrategy};
+  configurePostCss?(options: {[name: string]: any}): Configuration;
   getThemePath?(): string;
   getTypeScriptThemePath?(): string;
   getPathsToWatch?(): string[];
@@ -253,6 +254,7 @@ export interface Plugin<T, U = unknown> {
 
 export type ConfigureWebpackFn = Plugin<unknown>['configureWebpack'];
 export type ConfigureWebpackFnMergeStrategy = Record<string, MergeStrategy>;
+export type ConfigurePostCssFn = Plugin<unknown>['configurePostCss'];
 
 export type PluginOptions = {id?: string} & Record<string, unknown>;
 

packages/docusaurus/src/commands/build.ts

@@ -20,7 +20,11 @@ import {handleBrokenLinks} from '../server/brokenLinks';
 import {BuildCLIOptions, Props} from '@docusaurus/types';
 import createClientConfig from '../webpack/client';
 import createServerConfig from '../webpack/server';
-import {compile, applyConfigureWebpack} from '../webpack/utils';
+import {
+  compile,
+  applyConfigureWebpack,
+  applyConfigurePostCss,
+} from '../webpack/utils';
 import CleanWebpackPlugin from '../webpack/plugins/CleanWebpackPlugin';
 import {loadI18n} from '../server/i18n';
 import {mapAsyncSequencial} from '@docusaurus/utils';
@@ -166,24 +170,27 @@ async function buildLocale({
     });
   }
 
-  // Plugin Lifecycle - configureWebpack.
+  // Plugin Lifecycle - configureWebpack and configurePostCss.
   plugins.forEach((plugin) => {
-    const {configureWebpack} = plugin;
-    if (!configureWebpack) {
-      return;
+    const {configureWebpack, configurePostCss} = plugin;
+
+    if (configurePostCss) {
+      clientConfig = applyConfigurePostCss(configurePostCss, clientConfig);
     }
 
-    clientConfig = applyConfigureWebpack(
-      configureWebpack.bind(plugin), // The plugin lifecycle may reference `this`.
-      clientConfig,
-      false,
-    );
+    if (configureWebpack) {
+      clientConfig = applyConfigureWebpack(
+        configureWebpack.bind(plugin), // The plugin lifecycle may reference `this`.
+        clientConfig,
+        false,
+      );
 
-    serverConfig = applyConfigureWebpack(
-      configureWebpack.bind(plugin), // The plugin lifecycle may reference `this`.
-      serverConfig,
-      true,
-    );
+      serverConfig = applyConfigureWebpack(
+        configureWebpack.bind(plugin), // The plugin lifecycle may reference `this`.
+        serverConfig,
+        true,
+      );
+    }
   });
 
   // Make sure generated client-manifest is cleaned first so we don't reuse

packages/docusaurus/src/commands/start.ts

@@ -24,7 +24,11 @@ import {load} from '../server';
 import {StartCLIOptions} from '@docusaurus/types';
 import {CONFIG_FILE_NAME, STATIC_DIR_NAME} from '../constants';
 import createClientConfig from '../webpack/client';
-import {applyConfigureWebpack, getHttpsConfig} from '../webpack/utils';
+import {
+  applyConfigureWebpack,
+  applyConfigurePostCss,
+  getHttpsConfig,
+} from '../webpack/utils';
 import {getCLIOptionHost, getCLIOptionPort} from './commandUtils';
 import {getTranslationsLocaleDirPath} from '../server/translations/translations';
 
@@ -134,18 +138,21 @@ export default async function start(
     ],
   });
 
-  // Plugin Lifecycle - configureWebpack.
+  // Plugin Lifecycle - configureWebpack and configurePostCss.
   plugins.forEach((plugin) => {
-    const {configureWebpack} = plugin;
-    if (!configureWebpack) {
-      return;
+    const {configureWebpack, configurePostCss} = plugin;
+
+    if (configurePostCss) {
+      config = applyConfigurePostCss(configurePostCss, config);
     }
 
-    config = applyConfigureWebpack(
-      configureWebpack.bind(plugin), // The plugin lifecycle may reference `this`.
-      config,
-      false,
-    );
+    if (configureWebpack) {
+      config = applyConfigureWebpack(
+        configureWebpack.bind(plugin), // The plugin lifecycle may reference `this`.
+        config,
+        false,
+      );
+    }
   });
 
   // https://webpack.js.org/configuration/dev-server

packages/docusaurus/src/webpack/__tests__/utils.test.ts

@@ -12,10 +12,16 @@ import {
 } from 'webpack';
 import path from 'path';
 
-import {applyConfigureWebpack, getFileLoaderUtils} from '../utils';
+import {
+  applyConfigureWebpack,
+  applyConfigurePostCss,
+  getFileLoaderUtils,
+  getStyleLoaders,
+} from '../utils';
 import {
   ConfigureWebpackFn,
   ConfigureWebpackFnMergeStrategy,
+  ConfigurePostCssFn,
 } from '@docusaurus/types';
 
 describe('extending generated webpack config', () => {
@@ -148,3 +154,42 @@ describe('getFileLoaderUtils()', () => {
     );
   });
 });
+
+describe('extending PostCSS', () => {
+  test('user plugin should be appended in PostCSS loader', () => {
+    let config: Configuration = {
+      output: {
+        path: __dirname,
+        filename: 'bundle.js',
+      },
+      module: {
+        rules: [
+          {
+            test: /\.css$/,
+            use: getStyleLoaders(false),
+          },
+        ],
+      },
+    };
+    const postCssPlugin = jest.fn(() => {
+      return {
+        postcssPlugin: 'appended-plugin',
+      };
+    });
+    const configurePostCss: ConfigurePostCssFn = (postCssConfig) => {
+      postCssConfig.plugins.push(postCssPlugin());
+      return postCssConfig;
+    };
+
+    config = applyConfigurePostCss(configurePostCss, config);
+
+    const postCssLoader = config.module.rules[0].use.slice(-1)[0];
+    const postCssPlugins = postCssLoader.options.postcssOptions.plugins.map(
+      (plugin) => {
+        return plugin.postcssPlugin;
+      },
+    );
+
+    expect(postCssPlugins).toContain('appended-plugin');
+  });
+});

packages/docusaurus/src/webpack/utils.ts

@@ -11,6 +11,7 @@ import merge from 'webpack-merge';
 import webpack, {
   Configuration,
   Loader,
+  NewLoader,
   Plugin,
   RuleSetRule,
   Stats,
@@ -23,7 +24,7 @@ import path from 'path';
 import crypto from 'crypto';
 import chalk from 'chalk';
 import {TransformOptions} from '@babel/core';
-import {ConfigureWebpackFn} from '@docusaurus/types';
+import {ConfigureWebpackFn, ConfigurePostCssFn} from '@docusaurus/types';
 import CssNanoPreset from '@docusaurus/cssnano-preset';
 import {version as cacheLoaderVersion} from 'cache-loader/package.json';
 import {BABEL_CONFIG_FILE_NAME, STATIC_ASSETS_DIR_NAME} from '../constants';
@@ -175,6 +176,33 @@ export function applyConfigureWebpack(
   return config;
 }
 
+export function applyConfigurePostCss(
+  configurePostCss: ConfigurePostCssFn,
+  config: Configuration,
+): Configuration {
+  const isPostCssLoader = (loader) =>
+    JSON.stringify(loader).includes('postcss-loader');
+  const postCssLoader = getStyleLoaders(false).find((loader) =>
+    isPostCssLoader(loader),
+  ) as NewLoader;
+  const mutatedPostCssOptions = configurePostCss!(
+    postCssLoader?.options?.postcssOptions,
+  );
+
+  config.module?.rules
+    .filter((rule) => rule.test!.toString().includes('.css'))
+    .forEach((rule) => {
+      for (const loader of rule.use as NewLoader[]) {
+        if (isPostCssLoader(loader)) {
+          console.log(1, loader);
+          loader.options!.postcssOptions = mutatedPostCssOptions;
+        }
+      }
+    });
+
+  return config;
+}
+
 // See https://webpack.js.org/configuration/stats/#statswarningsfilter
 // @slorber: note sure why we have to re-implement this logic
 // just know that legacy had this only partially implemented, so completed it

website/docs/lifecycle-apis.md

@@ -346,6 +346,41 @@ module.exports = function (context, options) {
 
 Read the [webpack-merge strategy doc](https://github.com/survivejs/webpack-merge#merging-with-strategies) for more details.
 
+## `configurePostCss(options)`
+
+Modifies [`postcssOptions` of `postcss-loader`](https://webpack.js.org/loaders/postcss-loader/#postcssoptions) during generating client bundle. Should return mutated options.
+
+By default, `postcssOptions` looks like this:
+
+```js
+postcssOptions: {
+  ident: 'postcss',
+  plugins: [
+    require('postcss-preset-env')({
+      autoprefixer: {
+        flexbox: 'no-2009',
+      },
+      stage: 4,
+    }),
+  ],
+},
+```
+
+Example:
+
+```js {4-11} title="docusaurus-plugin/src/index.js"
+module.exports = function (context, options) {
+  return {
+    name: 'docusaurus-plugin',
+    configurePostCss(options) {
+      // Appends new PostCSS plugin.
+      options.plugins.push(require('postcss-import'));
+      return options;
+    },
+  };
+};
+```
+
 ## `postBuild(props)`
 
 Called when a (production) build finishes.