@docusaurus/core 3.1.1 → 3.2.0

package/lib/utils.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PerfLogger = exports.PerfDebuggingEnabled = void 0;
+const tslib_1 = require("tslib");
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+const async_hooks_1 = require("async_hooks");
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+// For now this is a private env variable we use internally
+// But we'll want to expose this feature officially some day
+exports.PerfDebuggingEnabled = !!process.env.DOCUSAURUS_PERF_LOGGER;
+const Thresholds = {
+    min: 5,
+    yellow: 100,
+    red: 1000,
+};
+const PerfPrefix = logger_1.default.yellow(`[PERF] `);
+// This is what enables to "see the parent stack" for each log
+// Parent1 > Parent2 > Parent3 > child trace
+const ParentPrefix = new async_hooks_1.AsyncLocalStorage();
+function applyParentPrefix(label) {
+    const parentPrefix = ParentPrefix.getStore();
+    return parentPrefix ? `${parentPrefix} > ${label}` : label;
+}
+function createPerfLogger() {
+    if (!exports.PerfDebuggingEnabled) {
+        const noop = () => { };
+        return {
+            start: noop,
+            end: noop,
+            log: noop,
+            async: async (_label, asyncFn) => asyncFn(),
+        };
+    }
+    const formatDuration = (duration) => {
+        if (duration > Thresholds.red) {
+            return logger_1.default.red(`${(duration / 1000).toFixed(2)} seconds!`);
+        }
+        else if (duration > Thresholds.yellow) {
+            return logger_1.default.yellow(`${duration.toFixed(2)} ms`);
+        }
+        else {
+            return logger_1.default.green(`${duration.toFixed(2)} ms`);
+        }
+    };
+    const logDuration = (label, duration) => {
+        if (duration < Thresholds.min) {
+            return;
+        }
+        console.log(`${PerfPrefix + label} - ${formatDuration(duration)}`);
+    };
+    const start = (label) => performance.mark(label);
+    const end = (label) => {
+        const { duration } = performance.measure(label);
+        performance.clearMarks(label);
+        logDuration(applyParentPrefix(label), duration);
+    };
+    const log = (label) => console.log(PerfPrefix + applyParentPrefix(label));
+    const async = async (label, asyncFn) => {
+        const finalLabel = applyParentPrefix(label);
+        const before = performance.now();
+        const result = await ParentPrefix.run(finalLabel, () => asyncFn());
+        const duration = performance.now() - before;
+        logDuration(finalLabel, duration);
+        return result;
+    };
+    return {
+        start,
+        end,
+        log,
+        async,
+    };
+}
+exports.PerfLogger = createPerfLogger();

package/lib/webpack/base.d.ts

@@ -8,4 +8,8 @@ import type { Configuration } from 'webpack';
 import type { Props } from '@docusaurus/types';
 export declare const clientDir: string;
 export declare function excludeJS(modulePath: string): boolean;
-export declare function createBaseConfig(props: Props, isServer: boolean, minify?: boolean): Promise<Configuration>;
+export declare function createBaseConfig({ props, isServer, minify, }: {
+    props: Props;
+    isServer: boolean;
+    minify: boolean;
+}): Promise<Configuration>;

package/lib/webpack/base.js

@@ -13,6 +13,7 @@ const path_1 = tslib_1.__importDefault(require("path"));
 const mini_css_extract_plugin_1 = tslib_1.__importDefault(require("mini-css-extract-plugin"));
 const utils_1 = require("@docusaurus/utils");
 const utils_2 = require("./utils");
+const minification_1 = require("./minification");
 const aliases_1 = require("./aliases");
 const CSS_REGEX = /\.css$/i;
 const CSS_MODULE_REGEX = /\.module\.css$/i;
@@ -32,12 +33,11 @@ function excludeJS(modulePath) {
         !LibrariesToTranspileRegex.test(modulePath));
 }
 exports.excludeJS = excludeJS;
-async function createBaseConfig(props, isServer, minify = true) {
+async function createBaseConfig({ props, isServer, minify, }) {
     const { outDir, siteDir, siteConfig, siteConfigPath, baseUrl, generatedFilesDir, routesPaths, siteMetadata, plugins, } = props;
     const totalPages = routesPaths.length;
     const isProd = process.env.NODE_ENV === 'production';
-    const minimizeEnabled = minify && isProd && !isServer;
-    const useSimpleCssMinifier = process.env.USE_SIMPLE_CSS_MINIFIER === 'true';
+    const minimizeEnabled = minify && isProd;
     const fileLoaderUtils = (0, utils_1.getFileLoaderUtils)();
     const name = isServer ? 'server' : 'client';
     const mode = isProd ? 'production' : 'development';
@@ -124,9 +124,7 @@ async function createBaseConfig(props, isServer, minify = true) {
             // Only minimize client bundle in production because server bundle is only
             // used for static site generation
             minimize: minimizeEnabled,
-            minimizer: minimizeEnabled
-                ? (0, utils_2.getMinimizer)(useSimpleCssMinifier)
-                : undefined,
+            minimizer: minimizeEnabled ? (0, minification_1.getMinimizer)() : undefined,
             splitChunks: isServer
                 ? false
                 : {

package/lib/webpack/client.d.ts

@@ -6,4 +6,18 @@
  */
 import type { Props } from '@docusaurus/types';
 import type { Configuration } from 'webpack';
-export default function createClientConfig(props: Props, minify?: boolean, hydrate?: boolean): Promise<Configuration>;
+export declare function createStartClientConfig({ props, minify, poll, }: {
+    props: Props;
+    minify: boolean;
+    poll: number | boolean | undefined;
+}): Promise<{
+    clientConfig: Configuration;
+}>;
+export declare function createBuildClientConfig({ props, minify, bundleAnalyzer, }: {
+    props: Props;
+    minify: boolean;
+    bundleAnalyzer: boolean;
+}): Promise<{
+    config: Configuration;
+    clientManifestPath: string;
+}>;

package/lib/webpack/client.js

@@ -6,19 +6,36 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBuildClientConfig = exports.createStartClientConfig = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const webpack_merge_1 = tslib_1.__importDefault(require("webpack-merge"));
 const webpackbar_1 = tslib_1.__importDefault(require("webpackbar"));
-const webpack_1 = require("webpack");
+const webpack_1 = tslib_1.__importDefault(require("webpack"));
+const webpack_bundle_analyzer_1 = require("webpack-bundle-analyzer");
+const react_loadable_ssr_addon_v5_slorber_1 = tslib_1.__importDefault(require("react-loadable-ssr-addon-v5-slorber"));
+const html_webpack_plugin_1 = tslib_1.__importDefault(require("html-webpack-plugin"));
 const base_1 = require("./base");
 const ChunkAssetPlugin_1 = tslib_1.__importDefault(require("./plugins/ChunkAssetPlugin"));
 const utils_1 = require("./utils");
-async function createClientConfig(props, minify = true, hydrate = true) {
-    const isBuilding = process.argv[2] === 'build';
-    const config = await (0, base_1.createBaseConfig)(props, false, minify);
-    const clientConfig = (0, webpack_merge_1.default)(config, {
+const CleanWebpackPlugin_1 = tslib_1.__importDefault(require("./plugins/CleanWebpackPlugin"));
+// When building, include the plugin to force terminate building if errors
+// happened in the client bundle.
+class ForceTerminatePlugin {
+    apply(compiler) {
+        compiler.hooks.done.tap('client:done', (stats) => {
+            if (stats.hasErrors()) {
+                const errorsWarnings = stats.toJson('errors-warnings');
+                logger_1.default.error(`Client bundle compiled with errors therefore further build is impossible.\n${(0, utils_1.formatStatsErrorMessage)(errorsWarnings)}`);
+                process.exit(1);
+            }
+        });
+    }
+}
+async function createBaseClientConfig({ props, hydrate, minify, }) {
+    const baseConfig = await (0, base_1.createBaseConfig)({ props, isServer: false, minify });
+    return (0, webpack_merge_1.default)(baseConfig, {
         // Useless, disabled on purpose (errors on existing sites with no
         // browserslist config)
         // target: 'browserslist',
@@ -29,7 +46,7 @@ async function createClientConfig(props, minify = true, hydrate = true) {
             runtimeChunk: true,
         },
         plugins: [
-            new webpack_1.DefinePlugin({
+            new webpack_1.default.DefinePlugin({
                 'process.env.HYDRATE_CLIENT_ENTRY': JSON.stringify(hydrate),
             }),
             new ChunkAssetPlugin_1.default(),
@@ -39,21 +56,59 @@ async function createClientConfig(props, minify = true, hydrate = true) {
             }),
         ],
     });
-    // When building, include the plugin to force terminate building if errors
-    // happened in the client bundle.
-    if (isBuilding) {
-        clientConfig.plugins?.push({
-            apply: (compiler) => {
-                compiler.hooks.done.tap('client:done', (stats) => {
-                    if (stats.hasErrors()) {
-                        const errorsWarnings = stats.toJson('errors-warnings');
-                        logger_1.default.error(`Client bundle compiled with errors therefore further build is impossible.\n${(0, utils_1.formatStatsErrorMessage)(errorsWarnings)}`);
-                        process.exit(1);
-                    }
-                });
-            },
-        });
-    }
-    return clientConfig;
 }
-exports.default = createClientConfig;
+// client config when running "docusaurus start"
+async function createStartClientConfig({ props, minify, poll, }) {
+    const { siteConfig, headTags, preBodyTags, postBodyTags } = props;
+    const clientConfig = (0, webpack_merge_1.default)(await createBaseClientConfig({
+        props,
+        minify,
+        hydrate: false,
+    }), {
+        watchOptions: {
+            ignored: /node_modules\/(?!@docusaurus)/,
+            poll,
+        },
+        infrastructureLogging: {
+            // Reduce log verbosity, see https://github.com/facebook/docusaurus/pull/5420#issuecomment-906613105
+            level: 'warn',
+        },
+        plugins: [
+            // Generates an `index.html` file with the <script> injected.
+            new html_webpack_plugin_1.default({
+                template: path_1.default.join(__dirname, '../templates/dev.html.template.ejs'),
+                // So we can define the position where the scripts are injected.
+                inject: false,
+                filename: 'index.html',
+                title: siteConfig.title,
+                headTags,
+                preBodyTags,
+                postBodyTags,
+            }),
+        ],
+    });
+    return { clientConfig };
+}
+exports.createStartClientConfig = createStartClientConfig;
+// client config when running "docusaurus build"
+async function createBuildClientConfig({ props, minify, bundleAnalyzer, }) {
+    // Apply user webpack config.
+    const { generatedFilesDir } = props;
+    const clientManifestPath = path_1.default.join(generatedFilesDir, 'client-manifest.json');
+    const config = (0, webpack_merge_1.default)(await createBaseClientConfig({ props, minify, hydrate: true }), {
+        plugins: [
+            new ForceTerminatePlugin(),
+            // Remove/clean build folders before building bundles.
+            new CleanWebpackPlugin_1.default({ verbose: false }),
+            // Visualize size of webpack output files with an interactive zoomable
+            // tree map.
+            bundleAnalyzer && new webpack_bundle_analyzer_1.BundleAnalyzerPlugin(),
+            // Generate client manifests file that will be used for server bundle.
+            new react_loadable_ssr_addon_v5_slorber_1.default({
+                filename: clientManifestPath,
+            }),
+        ].filter((x) => Boolean(x)),
+    });
+    return { config, clientManifestPath };
+}
+exports.createBuildClientConfig = createBuildClientConfig;

package/lib/webpack/minification.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { WebpackPluginInstance } from 'webpack';
+export declare function getMinimizer(): WebpackPluginInstance[];

package/lib/webpack/minification.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMinimizer = void 0;
+const tslib_1 = require("tslib");
+const terser_webpack_plugin_1 = tslib_1.__importDefault(require("terser-webpack-plugin"));
+const css_minimizer_webpack_plugin_1 = tslib_1.__importDefault(require("css-minimizer-webpack-plugin"));
+// See https://github.com/webpack-contrib/terser-webpack-plugin#parallel
+function getTerserParallel() {
+    let terserParallel = true;
+    if (process.env.TERSER_PARALLEL === 'false') {
+        terserParallel = false;
+    }
+    else if (process.env.TERSER_PARALLEL &&
+        parseInt(process.env.TERSER_PARALLEL, 10) > 0) {
+        terserParallel = parseInt(process.env.TERSER_PARALLEL, 10);
+    }
+    return terserParallel;
+}
+function getJsMinifierPlugin() {
+    return new terser_webpack_plugin_1.default({
+        parallel: getTerserParallel(),
+        terserOptions: {
+            parse: {
+                // We want uglify-js to parse ecma 8 code. However, we don't want it
+                // to apply any minification steps that turns valid ecma 5 code
+                // into invalid ecma 5 code. This is why the 'compress' and 'output'
+                // sections only apply transformations that are ecma 5 safe
+                // https://github.com/facebook/create-react-app/pull/4234
+                ecma: 2020,
+            },
+            compress: {
+                ecma: 5,
+            },
+            mangle: {
+                safari10: true,
+            },
+            output: {
+                ecma: 5,
+                comments: false,
+                // Turned on because emoji and regex is not minified properly using
+                // default. See https://github.com/facebook/create-react-app/issues/2488
+                ascii_only: true,
+            },
+        },
+    });
+}
+function getAdvancedCssMinifier() {
+    // Using the array syntax to add 2 minimizers
+    // see https://github.com/webpack-contrib/css-minimizer-webpack-plugin#array
+    return new css_minimizer_webpack_plugin_1.default({
+        minimizerOptions: [
+            // CssNano options
+            {
+                preset: require.resolve('@docusaurus/cssnano-preset'),
+            },
+            // CleanCss options
+            {
+                inline: false,
+                level: {
+                    1: {
+                        all: false,
+                        removeWhitespace: true,
+                    },
+                    2: {
+                        all: true,
+                        restructureRules: true,
+                        removeUnusedAtRules: false,
+                    },
+                },
+            },
+        ],
+        minify: [
+            css_minimizer_webpack_plugin_1.default.cssnanoMinify,
+            css_minimizer_webpack_plugin_1.default.cleanCssMinify,
+        ],
+    });
+}
+function getMinimizer() {
+    // This is an historical env variable to opt-out of the advanced minifier
+    // Sometimes there's a bug in it and people are happy to disable it
+    const useSimpleCssMinifier = process.env.USE_SIMPLE_CSS_MINIFIER === 'true';
+    const minimizer = [getJsMinifierPlugin()];
+    if (useSimpleCssMinifier) {
+        minimizer.push(new css_minimizer_webpack_plugin_1.default());
+    }
+    else {
+        minimizer.push(getAdvancedCssMinifier());
+    }
+    return minimizer;
+}
+exports.getMinimizer = getMinimizer;

package/lib/webpack/server.d.ts

@@ -4,9 +4,11 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { type Locals } from '@slorber/static-site-generator-webpack-plugin';
 import type { Props } from '@docusaurus/types';
 import type { Configuration } from 'webpack';
-export default function createServerConfig({ props, onLinksCollected, onHeadTagsCollected, }: Pick<Locals, 'onLinksCollected' | 'onHeadTagsCollected'> & {
+export default function createServerConfig(params: {
     props: Props;
-}): Promise<Configuration>;
+}): Promise<{
+    config: Configuration;
+    serverBundlePath: string;
+}>;

package/lib/webpack/server.js

@@ -8,76 +8,67 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
+const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
 const webpack_merge_1 = tslib_1.__importDefault(require("webpack-merge"));
 const utils_1 = require("@docusaurus/utils");
-// Forked for Docusaurus: https://github.com/slorber/static-site-generator-webpack-plugin
-const static_site_generator_webpack_plugin_1 = tslib_1.__importDefault(require("@slorber/static-site-generator-webpack-plugin"));
 const webpackbar_1 = tslib_1.__importDefault(require("webpackbar"));
+const copy_webpack_plugin_1 = tslib_1.__importDefault(require("copy-webpack-plugin"));
 const base_1 = require("./base");
-const WaitPlugin_1 = tslib_1.__importDefault(require("./plugins/WaitPlugin"));
-const ssr_html_template_1 = tslib_1.__importDefault(require("./templates/ssr.html.template"));
-async function createServerConfig({ props, onLinksCollected, onHeadTagsCollected, }) {
-    const { baseUrl, routesPaths, generatedFilesDir, headTags, preBodyTags, postBodyTags, siteConfig: { noIndex, trailingSlash, ssrTemplate }, } = props;
-    const config = await (0, base_1.createBaseConfig)(props, true);
-    const routesLocation = {};
-    // Array of paths to be rendered. Relative to output directory
-    const ssgPaths = routesPaths.map((str) => {
-        const ssgPath = baseUrl === '/' ? str : str.replace(new RegExp(`^${baseUrl}`), '/');
-        routesLocation[ssgPath] = str;
-        return ssgPath;
+async function createServerConfig(params) {
+    const { props } = params;
+    const baseConfig = await (0, base_1.createBaseConfig)({
+        props,
+        isServer: true,
+        // Minification of server bundle reduces size but doubles bundle time :/
+        minify: false,
     });
-    const serverConfig = (0, webpack_merge_1.default)(config, {
+    const outputFilename = 'server.bundle.js';
+    const serverBundlePath = path_1.default.join(props.outDir, outputFilename);
+    const config = (0, webpack_merge_1.default)(baseConfig, {
         target: `node${utils_1.NODE_MAJOR_VERSION}.${utils_1.NODE_MINOR_VERSION}`,
         entry: {
             main: path_1.default.resolve(__dirname, '../client/serverEntry.js'),
         },
         output: {
-            filename: 'server.bundle.js',
+            filename: outputFilename,
             libraryTarget: 'commonjs2',
             // Workaround for Webpack 4 Bug (https://github.com/webpack/webpack/issues/6522)
             globalObject: 'this',
         },
         plugins: [
-            // Wait until manifest from client bundle is generated
-            new WaitPlugin_1.default({
-                filepath: path_1.default.join(generatedFilesDir, 'client-manifest.json'),
-            }),
-            // Static site generator webpack plugin.
-            new static_site_generator_webpack_plugin_1.default({
-                entry: 'main',
-                locals: {
-                    baseUrl,
-                    generatedFilesDir,
-                    routesLocation,
-                    headTags,
-                    preBodyTags,
-                    postBodyTags,
-                    onLinksCollected,
-                    onHeadTagsCollected,
-                    ssrTemplate: ssrTemplate ?? ssr_html_template_1.default,
-                    noIndex,
-                    DOCUSAURUS_VERSION: utils_1.DOCUSAURUS_VERSION,
-                },
-                paths: ssgPaths,
-                preferFoldersOutput: trailingSlash,
-                // When using "new URL('file.js', import.meta.url)", Webpack will emit
-                // __filename, and this plugin will throw. not sure the __filename value
-                // has any importance for this plugin, just using an empty string to
-                // avoid the error. See https://github.com/facebook/docusaurus/issues/4922
-                globals: { __filename: '' },
-                // Secret way to set SSR plugin concurrency option
-                // Waiting for feedback before documenting this officially?
-                concurrency: process.env.DOCUSAURUS_SSR_CONCURRENCY
-                    ? parseInt(process.env.DOCUSAURUS_SSR_CONCURRENCY, 10)
-                    : undefined,
-            }),
             // Show compilation progress bar.
             new webpackbar_1.default({
                 name: 'Server',
                 color: 'yellow',
             }),
-        ],
+            await createStaticDirectoriesCopyPlugin(params),
+        ].filter(Boolean),
     });
-    return serverConfig;
+    return { config, serverBundlePath };
 }
 exports.default = createServerConfig;
+async function createStaticDirectoriesCopyPlugin({ props }) {
+    const { outDir, siteDir, siteConfig: { staticDirectories: staticDirectoriesOption }, } = props;
+    // The staticDirectories option can contain empty directories, or non-existent
+    // directories (e.g. user deleted `static`). Instead of issuing an error, we
+    // just silently filter them out, because user could have never configured it
+    // in the first place (the default option should always "work").
+    const staticDirectories = (await Promise.all(staticDirectoriesOption.map(async (dir) => {
+        const staticDir = path_1.default.resolve(siteDir, dir);
+        if ((await fs_extra_1.default.pathExists(staticDir)) &&
+            (await fs_extra_1.default.readdir(staticDir)).length > 0) {
+            return staticDir;
+        }
+        return '';
+    }))).filter(Boolean);
+    if (staticDirectories.length === 0) {
+        return undefined;
+    }
+    return new copy_webpack_plugin_1.default({
+        patterns: staticDirectories.map((dir) => ({
+            from: dir,
+            to: outDir,
+            toType: 'dir',
+        })),
+    });
+}

package/lib/webpack/utils.d.ts

@@ -5,9 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="node" />
-import webpack, { type Configuration, type RuleSetRule, type WebpackPluginInstance } from 'webpack';
+import webpack, { type Configuration, type RuleSetRule } from 'webpack';
 import type { TransformOptions } from '@babel/core';
-import type { Plugin } from '@docusaurus/types';
+import type { Plugin, LoadedPlugin } from '@docusaurus/types';
 export declare function formatStatsErrorMessage(statsJson: ReturnType<webpack.Stats['toJson']> | undefined): string | undefined;
 export declare function printStatsWarnings(statsJson: ReturnType<webpack.Stats['toJson']> | undefined): void;
 export declare function getStyleLoaders(isServer: boolean, cssOptionsArg?: {
@@ -33,15 +33,24 @@ export declare const getCustomizableJSLoader: (jsLoader?: "babel" | ((isServer:
  */
 export declare function applyConfigureWebpack(configureWebpack: NonNullable<Plugin['configureWebpack']>, config: Configuration, isServer: boolean, jsLoader: 'babel' | ((isServer: boolean) => RuleSetRule) | undefined, content: unknown): Configuration;
 export declare function applyConfigurePostCss(configurePostCss: NonNullable<Plugin['configurePostCss']>, config: Configuration): Configuration;
+export declare function executePluginsConfigurePostCss({ plugins, config, }: {
+    plugins: LoadedPlugin[];
+    config: Configuration;
+}): Configuration;
+export declare function executePluginsConfigureWebpack({ plugins, config, isServer, jsLoader, }: {
+    plugins: LoadedPlugin[];
+    config: Configuration;
+    isServer: boolean;
+    jsLoader: 'babel' | ((isServer: boolean) => RuleSetRule) | undefined;
+}): Configuration;
 declare global {
     interface Error {
         /** @see https://webpack.js.org/api/node/#error-handling */
         details: unknown;
     }
 }
-export declare function compile(config: Configuration[]): Promise<void>;
+export declare function compile(config: Configuration[]): Promise<webpack.MultiStats>;
 export declare function getHttpsConfig(): Promise<boolean | {
     cert: Buffer;
     key: Buffer;
 }>;
-export declare function getMinimizer(useSimpleCssMinifier?: boolean): WebpackPluginInstance[];