@docusaurus/core 0.0.0-6110 → 0.0.0-6112

package/bin/docusaurus.mjs

@@ -33,6 +33,15 @@ process.env.NODE_ENV ??= 'development';
 
 await beforeCli();
 
+/**
+ * @param {string} locale
+ * @param {string[]} locales
+ * @returns {string[]}
+ */
+function concatLocaleOptions(locale, locales = []) {
+  return locales.concat(locale);
+}
+
 cli.version(DOCUSAURUS_VERSION).usage('<command> [options]');
 
 cli
@@ -55,8 +64,9 @@ cli
     'path to docusaurus config file (default: `[siteDir]/docusaurus.config.js`)',
   )
   .option(
-    '-l, --locale <locale>',
-    'build the site in a specified locale. Build all known locales otherwise',
+    '-l, --locale <locale...>',
+    'build the site in the specified locale(s). Build all known locales otherwise',
+    concatLocaleOptions,
   )
   .option(
     '--no-minify',
@@ -101,7 +111,8 @@ cli
   .description('Deploy website to GitHub pages.')
   .option(
     '-l, --locale <locale>',
-    'deploy the site in a specified locale. Deploy all known locales otherwise',
+    'deploy the site in the specified locale(s). Deploy all known locales otherwise',
+    concatLocaleOptions,
   )
   .option(
     '--out-dir <dir>',

package/lib/client/serverEntry.d.ts

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { AppRenderer } from '../common';
-declare const render: AppRenderer;
+declare const render: AppRenderer['render'];
 export default render;

package/lib/commands/{build.d.ts → build/build.d.ts}

@@ -4,8 +4,9 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { type LoadContextParams } from '../server/site';
-export type BuildCLIOptions = Pick<LoadContextParams, 'config' | 'locale' | 'outDir'> & {
+import { type LoadContextParams } from '../../server/site';
+export type BuildCLIOptions = Pick<LoadContextParams, 'config' | 'outDir'> & {
+    locale?: [string, ...string[]];
     bundleAnalyzer?: boolean;
     minify?: boolean;
     dev?: boolean;

package/lib/commands/build/build.js

@@ -0,0 +1,95 @@
+"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.build = build;
+const tslib_1 = require("tslib");
+const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
+const logger_1 = tslib_1.__importStar(require("@docusaurus/logger"));
+const utils_1 = require("@docusaurus/utils");
+const site_1 = require("../../server/site");
+const i18n_1 = require("../../server/i18n");
+const buildLocale_1 = require("./buildLocale");
+async function build(siteDirParam = '.', cliOptions = {}) {
+    process.env.BABEL_ENV = 'production';
+    process.env.NODE_ENV = 'production';
+    process.env.DOCUSAURUS_CURRENT_LOCALE = cliOptions.locale?.[0];
+    if (cliOptions.dev) {
+        logger_1.default.info `Building in dev mode`;
+        process.env.BABEL_ENV = 'development';
+        process.env.NODE_ENV = 'development';
+    }
+    const siteDir = await fs_extra_1.default.realpath(siteDirParam);
+    ['SIGINT', 'SIGTERM'].forEach((sig) => {
+        process.on(sig, () => process.exit());
+    });
+    const locales = await logger_1.PerfLogger.async('Get locales to build', () => getLocalesToBuild({ siteDir, cliOptions }));
+    if (locales.length > 1) {
+        logger_1.default.info `Website will be built for all these locales: ${locales}`;
+    }
+    await logger_1.PerfLogger.async(`Build`, () => (0, utils_1.mapAsyncSequential)(locales, async (locale) => {
+        await tryToBuildLocale({ siteDir, locale, cliOptions });
+    }));
+    logger_1.default.info `Use code=${'npm run serve'} command to test your build locally.`;
+}
+// We need the default locale to always be the 1st in the list. If we build it
+// last, it would "erase" the localized sites built in sub-folders
+function orderLocales({ locales, defaultLocale, }) {
+    if (locales.includes(defaultLocale)) {
+        return [
+            defaultLocale,
+            ...locales.filter((locale) => locale !== defaultLocale),
+        ];
+    }
+    else {
+        return locales;
+    }
+}
+async function getLocalesToBuild({ siteDir, cliOptions, }) {
+    // We disable locale path localization if CLI has single "--locale" option
+    // yarn build --locale fr => baseUrl=/ instead of baseUrl=/fr/
+    const localizePath = cliOptions.locale?.length === 1 ? false : undefined;
+    const context = await (0, site_1.loadContext)({
+        siteDir,
+        outDir: cliOptions.outDir,
+        config: cliOptions.config,
+        localizePath,
+    });
+    const i18n = await (0, i18n_1.loadI18n)(context.siteConfig);
+    const locales = cliOptions.locale ?? i18n.locales;
+    return orderLocales({
+        locales: locales,
+        defaultLocale: i18n.defaultLocale,
+    });
+}
+async function tryToBuildLocale(params) {
+    try {
+        await logger_1.PerfLogger.async(`${logger_1.default.name(params.locale)}`, async () => {
+            // Note: I tried to run buildLocale in worker_threads (still sequentially)
+            // It didn't work and I got SIGSEGV / SIGBUS errors
+            // See https://x.com/sebastienlorber/status/1848413716372480338
+            await runBuildLocaleTask(params);
+        });
+    }
+    catch (err) {
+        throw new Error(logger_1.default.interpolate `Unable to build website for locale name=${params.locale}.`, {
+            cause: err,
+        });
+    }
+}
+async function runBuildLocaleTask(params) {
+    // Note: I tried to run buildLocale task in worker_threads (sequentially)
+    // It didn't work and I got SIGSEGV / SIGBUS errors
+    // Goal was to isolate memory of each localized site build
+    // See also https://x.com/sebastienlorber/status/1848413716372480338
+    //
+    // Running in child_process worked but is more complex and requires
+    // specifying the memory of the child process + weird logging issues to fix
+    //
+    // Note in the future we could try to enable concurrent localized site builds
+    await (0, buildLocale_1.buildLocale)(params);
+}

package/lib/commands/build/buildLocale.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 { BuildCLIOptions } from './build';
+export type BuildLocaleParams = {
+    siteDir: string;
+    locale: string;
+    cliOptions: Partial<BuildCLIOptions>;
+};
+export declare function buildLocale({ siteDir, locale, cliOptions, }: BuildLocaleParams): Promise<void>;

package/lib/commands/{build.js → build/buildLocale.js}

@@ -6,81 +6,19 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.build = build;
+exports.buildLocale = buildLocale;
 const tslib_1 = require("tslib");
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
 const path_1 = tslib_1.__importDefault(require("path"));
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const bundler_1 = require("@docusaurus/bundler");
 const logger_1 = tslib_1.__importStar(require("@docusaurus/logger"));
-const utils_1 = require("@docusaurus/utils");
-const site_1 = require("../server/site");
-const brokenLinks_1 = require("../server/brokenLinks");
-const client_1 = require("../webpack/client");
-const server_1 = tslib_1.__importDefault(require("../webpack/server"));
-const configure_1 = require("../webpack/configure");
-const i18n_1 = require("../server/i18n");
-const ssgExecutor_1 = require("../ssg/ssgExecutor");
-async function build(siteDirParam = '.', cliOptions = {}) {
-    process.env.BABEL_ENV = 'production';
-    process.env.NODE_ENV = 'production';
-    process.env.DOCUSAURUS_CURRENT_LOCALE = cliOptions.locale;
-    if (cliOptions.dev) {
-        logger_1.default.info `Building in dev mode`;
-        process.env.BABEL_ENV = 'development';
-        process.env.NODE_ENV = 'development';
-    }
-    const siteDir = await fs_extra_1.default.realpath(siteDirParam);
-    ['SIGINT', 'SIGTERM'].forEach((sig) => {
-        process.on(sig, () => process.exit());
-    });
-    async function tryToBuildLocale({ locale }) {
-        try {
-            await logger_1.PerfLogger.async(`${logger_1.default.name(locale)}`, () => buildLocale({
-                siteDir,
-                locale,
-                cliOptions,
-            }));
-        }
-        catch (err) {
-            throw new Error(logger_1.default.interpolate `Unable to build website for locale name=${locale}.`, {
-                cause: err,
-            });
-        }
-    }
-    const locales = await logger_1.PerfLogger.async('Get locales to build', () => getLocalesToBuild({ siteDir, cliOptions }));
-    if (locales.length > 1) {
-        logger_1.default.info `Website will be built for all these locales: ${locales}`;
-    }
-    await logger_1.PerfLogger.async(`Build`, () => (0, utils_1.mapAsyncSequential)(locales, async (locale) => {
-        await tryToBuildLocale({ locale });
-    }));
-    logger_1.default.info `Use code=${'npm run serve'} command to test your build locally.`;
-}
-async function getLocalesToBuild({ siteDir, cliOptions, }) {
-    if (cliOptions.locale) {
-        return [cliOptions.locale];
-    }
-    const context = await (0, site_1.loadContext)({
-        siteDir,
-        outDir: cliOptions.outDir,
-        config: cliOptions.config,
-        locale: cliOptions.locale,
-        localizePath: cliOptions.locale ? false : undefined,
-    });
-    const i18n = await (0, i18n_1.loadI18n)(context.siteConfig, {
-        locale: cliOptions.locale,
-    });
-    if (i18n.locales.length > 1) {
-        logger_1.default.info `Website will be built for all these locales: ${i18n.locales}`;
-    }
-    // We need the default locale to always be the 1st in the list. If we build it
-    // last, it would "erase" the localized sites built in sub-folders
-    return [
-        i18n.defaultLocale,
-        ...i18n.locales.filter((locale) => locale !== i18n.defaultLocale),
-    ];
-}
+const site_1 = require("../../server/site");
+const brokenLinks_1 = require("../../server/brokenLinks");
+const client_1 = require("../../webpack/client");
+const server_1 = tslib_1.__importDefault(require("../../webpack/server"));
+const configure_1 = require("../../webpack/configure");
+const ssgExecutor_1 = require("../../ssg/ssgExecutor");
 async function buildLocale({ siteDir, locale, cliOptions, }) {
     // Temporary workaround to unlock the ability to translate the site config
     // We'll remove it if a better official API can be designed
@@ -92,7 +30,7 @@ async function buildLocale({ siteDir, locale, cliOptions, }) {
         outDir: cliOptions.outDir,
         config: cliOptions.config,
         locale,
-        localizePath: cliOptions.locale ? false : undefined,
+        localizePath: cliOptions.locale?.length === 1 ? false : undefined,
     }));
     const { props } = site;
     const { outDir, plugins, siteConfig } = props;

package/lib/commands/deploy.d.ts

@@ -5,7 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { type LoadContextParams } from '../server/site';
-export type DeployCLIOptions = Pick<LoadContextParams, 'config' | 'locale' | 'outDir'> & {
+export type DeployCLIOptions = Pick<LoadContextParams, 'config' | 'outDir'> & {
+    locale?: [string, ...string[]];
     skipBuild?: boolean;
     targetDir?: string;
 };

package/lib/commands/deploy.js

@@ -15,7 +15,7 @@ const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const shelljs_1 = tslib_1.__importDefault(require("shelljs"));
 const utils_1 = require("@docusaurus/utils");
 const site_1 = require("../server/site");
-const build_1 = require("./build");
+const build_1 = require("./build/build");
 // GIT_PASS env variable should not appear in logs
 function obfuscateGitPass(str) {
     const gitPass = process.env.GIT_PASS;

package/lib/commands/serve.js

@@ -17,7 +17,7 @@ const serve_handler_1 = tslib_1.__importDefault(require("serve-handler"));
 const openBrowser_1 = tslib_1.__importDefault(require("react-dev-utils/openBrowser"));
 const utils_common_1 = require("@docusaurus/utils-common");
 const config_1 = require("../server/config");
-const build_1 = require("./build");
+const build_1 = require("./build/build");
 const getHostPort_1 = require("../server/getHostPort");
 function redirect(res, location) {
     res.writeHead(302, {

package/lib/index.d.ts

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export { build } from './commands/build';
+export { build } from './commands/build/build';
 export { clear } from './commands/clear';
 export { deploy } from './commands/deploy';
 export { externalCommand } from './commands/external';

package/lib/index.js

@@ -7,7 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.writeTranslations = exports.writeHeadingIds = exports.swizzle = exports.start = exports.serve = exports.externalCommand = exports.deploy = exports.clear = exports.build = void 0;
-var build_1 = require("./commands/build");
+var build_1 = require("./commands/build/build");
 Object.defineProperty(exports, "build", { enumerable: true, get: function () { return build_1.build; } });
 var clear_1 = require("./commands/clear");
 Object.defineProperty(exports, "clear", { enumerable: true, get: function () { return clear_1.clear; } });

package/lib/server/i18n.d.ts

@@ -7,4 +7,4 @@
 import type { I18n, DocusaurusConfig, I18nLocaleConfig } from '@docusaurus/types';
 import type { LoadContextParams } from './site';
 export declare function getDefaultLocaleConfig(locale: string): I18nLocaleConfig;
-export declare function loadI18n(config: DocusaurusConfig, options: Pick<LoadContextParams, 'locale'>): Promise<I18n>;
+export declare function loadI18n(config: DocusaurusConfig, options?: Pick<LoadContextParams, 'locale'>): Promise<I18n>;

package/lib/server/i18n.js

@@ -74,7 +74,7 @@ function getDefaultLocaleConfig(locale) {
 }
 async function loadI18n(config, options) {
     const { i18n: i18nConfig } = config;
-    const currentLocale = options.locale ?? i18nConfig.defaultLocale;
+    const currentLocale = options?.locale ?? i18nConfig.defaultLocale;
     if (!i18nConfig.locales.includes(currentLocale)) {
         logger_1.default.warn `The locale name=${currentLocale} was not found in your site configuration: Available locales are: ${i18nConfig.locales}
 Note: Docusaurus only support running one locale at a time.`;

package/lib/ssg/ssg.js

@@ -11,19 +11,22 @@ exports.printSSGWarnings = printSSGWarnings;
 exports.generateStaticFiles = generateStaticFiles;
 const tslib_1 = require("tslib");
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
-const module_1 = require("module");
 const path_1 = tslib_1.__importDefault(require("path"));
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
+// TODO eval is archived / unmaintained: https://github.com/pierrec/node-eval
+//  We should internalize/modernize it
 const eval_1 = tslib_1.__importDefault(require("eval"));
 const p_map_1 = tslib_1.__importDefault(require("p-map"));
 const logger_1 = tslib_1.__importStar(require("@docusaurus/logger"));
 const bundler_1 = require("@docusaurus/bundler");
 const ssgTemplate_1 = require("./ssgTemplate");
 const ssgUtils_1 = require("./ssgUtils");
+const ssgNodeRequire_1 = require("./ssgNodeRequire");
 async function loadAppRenderer({ serverBundlePath, }) {
     const source = await logger_1.PerfLogger.async(`Load server bundle`, () => fs_extra_1.default.readFile(serverBundlePath));
     logger_1.PerfLogger.log(`Server bundle size = ${(source.length / 1024000).toFixed(3)} MB`);
     const filename = path_1.default.basename(serverBundlePath);
+    const ssgRequire = (0, ssgNodeRequire_1.createSSGRequire)(serverBundlePath);
     const globals = {
         // When using "new URL('file.js', import.meta.url)", Webpack will emit
         // __filename, and this plugin will throw. not sure the __filename value
@@ -32,7 +35,7 @@ async function loadAppRenderer({ serverBundlePath, }) {
         __filename: '',
         // This uses module.createRequire() instead of very old "require-like" lib
         // See also: https://github.com/pierrec/node-eval/issues/33
-        require: (0, module_1.createRequire)(serverBundlePath),
+        require: ssgRequire.require,
     };
     const serverEntry = await logger_1.PerfLogger.async(`Evaluate server bundle`, () => (0, eval_1.default)(source, 
     /* filename: */ filename, 
@@ -41,7 +44,13 @@ async function loadAppRenderer({ serverBundlePath, }) {
     if (!serverEntry?.default || typeof serverEntry.default !== 'function') {
         throw new Error(`Server bundle export from "${filename}" must be a function that renders the Docusaurus React app.`);
     }
-    return serverEntry.default;
+    async function shutdown() {
+        ssgRequire.cleanup();
+    }
+    return {
+        render: serverEntry.default,
+        shutdown,
+    };
 }
 function printSSGWarnings(results) {
     // Escape hatch because SWC is quite aggressive to report errors
@@ -108,6 +117,7 @@ async function generateStaticFiles({ pathnames, params, }) {
         error: error,
         warnings: [],
     })), { concurrency: ssgUtils_1.SSGConcurrency });
+    await renderer.shutdown();
     printSSGWarnings(results);
     const [allSSGErrors, allSSGSuccesses] = lodash_1.default.partition(results, (result) => !!result.error);
     if (allSSGErrors.length > 0) {
@@ -129,7 +139,7 @@ async function generateStaticFiles({ pathnames, params, }) {
 async function generateStaticFile({ pathname, renderer, params, htmlMinifier, ssgTemplate, }) {
     try {
         // This only renders the app HTML
-        const result = await renderer({
+        const result = await renderer.render({
             pathname,
         });
         // This renders the full page HTML, including head tags...

package/lib/ssg/ssgNodeRequire.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+export type SSGNodeRequire = {
+    require: NodeJS.Require;
+    cleanup: () => void;
+};
+export declare function createSSGRequire(serverBundlePath: string): SSGNodeRequire;

package/lib/ssg/ssgNodeRequire.js

@@ -0,0 +1,40 @@
+"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.createSSGRequire = createSSGRequire;
+const module_1 = require("module");
+// The eval/vm.Script used for running the server bundle need a require() impl
+// This impl has to be relative to the server bundler path
+// This enables the server bundle to resolve relative paths such as:
+// - require('./assets/js/some-chunk.123456.js')
+//
+// Unfortunately, Node.js vm.Script doesn't isolate memory / require.cache
+// This means that if we build multiple Docusaurus localized sites in a row
+// The Node.js require cache will keep growing and retain in memory the JS
+// assets of the former SSG builds
+// We have to clean up the node require cache manually to avoid leaking memory!
+// See also https://x.com/sebastienlorber/status/1848399310116831702
+function createSSGRequire(serverBundlePath) {
+    const realRequire = (0, module_1.createRequire)(serverBundlePath);
+    const allRequiredIds = [];
+    const ssgRequireFunction = (id) => {
+        const module = realRequire(id);
+        allRequiredIds.push(id);
+        return module;
+    };
+    const cleanup = () => {
+        allRequiredIds.forEach((id) => {
+            delete realRequire.cache[realRequire.resolve(id)];
+        });
+    };
+    ssgRequireFunction.resolve = realRequire.resolve;
+    ssgRequireFunction.cache = realRequire.cache;
+    ssgRequireFunction.extensions = realRequire.extensions;
+    ssgRequireFunction.main = realRequire.main;
+    return { require: ssgRequireFunction, cleanup };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docusaurus/core",
   "description": "Easy to Maintain Open Source Documentation Websites",
-  "version": "0.0.0-6110",
+  "version": "0.0.0-6112",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -33,13 +33,13 @@
     "url": "https://github.com/facebook/docusaurus/issues"
   },
   "dependencies": {
-    "@docusaurus/babel": "0.0.0-6110",
-    "@docusaurus/bundler": "0.0.0-6110",
-    "@docusaurus/logger": "0.0.0-6110",
-    "@docusaurus/mdx-loader": "0.0.0-6110",
-    "@docusaurus/utils": "0.0.0-6110",
-    "@docusaurus/utils-common": "0.0.0-6110",
-    "@docusaurus/utils-validation": "0.0.0-6110",
+    "@docusaurus/babel": "0.0.0-6112",
+    "@docusaurus/bundler": "0.0.0-6112",
+    "@docusaurus/logger": "0.0.0-6112",
+    "@docusaurus/mdx-loader": "0.0.0-6112",
+    "@docusaurus/utils": "0.0.0-6112",
+    "@docusaurus/utils-common": "0.0.0-6112",
+    "@docusaurus/utils-validation": "0.0.0-6112",
     "boxen": "^6.2.1",
     "chalk": "^4.1.2",
     "chokidar": "^3.5.3",
@@ -78,8 +78,8 @@
     "webpack-merge": "^6.0.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-6110",
-    "@docusaurus/types": "0.0.0-6110",
+    "@docusaurus/module-type-aliases": "0.0.0-6112",
+    "@docusaurus/types": "0.0.0-6112",
     "@total-typescript/shoehorn": "^0.1.2",
     "@types/detect-port": "^1.3.3",
     "@types/react-dom": "^18.2.7",
@@ -100,5 +100,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "3e5c6c714c37c6d3592bfc2a0679dbff3d825b3e"
+  "gitHead": "dd7a8f35cefc9d93e08d19e6959c45c41a811739"
 }