@docusaurus/core 0.0.0-5857 → 0.0.0-5860

package/lib/server/routes.js

@@ -6,115 +6,23 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadRoutes = exports.handleDuplicateRoutes = exports.genChunkName = void 0;
+exports.getRoutesPaths = exports.handleDuplicateRoutes = exports.getAllFinalRoutes = void 0;
 const tslib_1 = require("tslib");
-const querystring_1 = tslib_1.__importDefault(require("querystring"));
-const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
-const utils_2 = require("./utils");
-/** Indents every line of `str` by one level. */
-function indent(str) {
-    return `  ${str.replace(/\n/g, `\n  `)}`;
-}
-const chunkNameCache = new Map();
-const chunkNameCount = new Map();
-/**
- * Generates a unique chunk name that can be used in the chunk registry.
- *
- * @param modulePath A path to generate chunk name from. The actual value has no
- * semantic significance.
- * @param prefix A prefix to append to the chunk name, to avoid name clash.
- * @param preferredName Chunk names default to `modulePath`, and this can supply
- * a more human-readable name.
- * @param shortId When `true`, the chunk name would only be a hash without any
- * other characters. Useful for bundle size. Defaults to `true` in production.
- */
-function genChunkName(modulePath, prefix, preferredName, shortId = process.env.NODE_ENV === 'production') {
-    let chunkName = chunkNameCache.get(modulePath);
-    if (!chunkName) {
-        if (shortId) {
-            chunkName = (0, utils_1.simpleHash)(modulePath, 8);
-        }
-        else {
-            let str = modulePath;
-            if (preferredName) {
-                const shortHash = (0, utils_1.simpleHash)(modulePath, 3);
-                str = `${preferredName}${shortHash}`;
-            }
-            const name = (0, utils_1.docuHash)(str);
-            chunkName = prefix ? `${prefix}---${name}` : name;
-        }
-        const seenCount = (chunkNameCount.get(chunkName) ?? 0) + 1;
-        if (seenCount > 1) {
-            chunkName += seenCount.toString(36);
-        }
-        chunkNameCache.set(modulePath, chunkName);
-        chunkNameCount.set(chunkName, seenCount);
-    }
-    return chunkName;
-}
-exports.genChunkName = genChunkName;
-/**
- * Takes a piece of route config, and serializes it into raw JS code. The shape
- * is the same as react-router's `RouteConfig`. Formatting is similar to
- * `JSON.stringify` but without all the quotes.
- */
-function serializeRouteConfig({ routePath, routeHash, exact, subroutesCodeStrings, props, }) {
-    const parts = [
-        `path: '${routePath}'`,
-        `component: ComponentCreator('${routePath}', '${routeHash}')`,
-    ];
-    if (exact) {
-        parts.push(`exact: true`);
+// Recursively get the final routes (routes with no subroutes)
+function getAllFinalRoutes(routeConfig) {
+    function getFinalRoutes(route) {
+        return route.routes ? route.routes.flatMap(getFinalRoutes) : [route];
     }
-    if (subroutesCodeStrings) {
-        parts.push(`routes: [
-${indent(subroutesCodeStrings.join(',\n'))}
-]`);
-    }
-    Object.entries(props).forEach(([propName, propValue]) => {
-        const isIdentifier = /^[$_\p{ID_Start}][$\u200c\u200d\p{ID_Continue}]*$/u.test(propName);
-        const key = isIdentifier ? propName : JSON.stringify(propName);
-        parts.push(`${key}: ${JSON.stringify(propValue)}`);
-    });
-    return `{
-${indent(parts.join(',\n'))}
-}`;
+    return routeConfig.flatMap(getFinalRoutes);
 }
-const isModule = (value) => typeof value === 'string' ||
-    (typeof value === 'object' &&
-        // eslint-disable-next-line no-underscore-dangle
-        !!value?.__import);
-/**
- * Takes a {@link Module} (which is nothing more than a path plus some metadata
- * like query) and returns the string path it represents.
- */
-function getModulePath(target) {
-    if (typeof target === 'string') {
-        return target;
-    }
-    const queryStr = target.query ? `?${querystring_1.default.stringify(target.query)}` : '';
-    return `${target.path}${queryStr}`;
-}
-function genChunkNames(routeModule, prefix, name, res) {
-    if (isModule(routeModule)) {
-        // This is a leaf node, no need to recurse
-        const modulePath = getModulePath(routeModule);
-        const chunkName = genChunkName(modulePath, prefix, name);
-        res.registry[chunkName] = (0, utils_1.escapePath)(modulePath);
-        return chunkName;
-    }
-    if (Array.isArray(routeModule)) {
-        return routeModule.map((val, index) => genChunkNames(val, `${index}`, name, res));
-    }
-    return lodash_1.default.mapValues(routeModule, (v, key) => genChunkNames(v, key, name, res));
-}
-function handleDuplicateRoutes(pluginsRouteConfigs, onDuplicateRoutes) {
+exports.getAllFinalRoutes = getAllFinalRoutes;
+function handleDuplicateRoutes(routes, onDuplicateRoutes) {
     if (onDuplicateRoutes === 'ignore') {
         return;
     }
-    const allRoutes = (0, utils_2.getAllFinalRoutes)(pluginsRouteConfigs).map((routeConfig) => routeConfig.path);
+    const allRoutes = getAllFinalRoutes(routes).map((routeConfig) => routeConfig.path);
     const seenRoutes = new Set();
     const duplicatePaths = allRoutes.filter((route) => {
         if (seenRoutes.has(route)) {
@@ -129,36 +37,6 @@ This could lead to non-deterministic routing behavior.`;
     }
 }
 exports.handleDuplicateRoutes = handleDuplicateRoutes;
-/**
- * This is the higher level overview of route code generation. For each route
- * config node, it returns the node's serialized form, and mutates `registry`,
- * `routesPaths`, and `routesChunkNames` accordingly.
- */
-function genRouteCode(routeConfig, res) {
-    const { path: routePath, component, modules = {}, context, routes: subroutes, priority, exact, ...props } = routeConfig;
-    if (typeof routePath !== 'string' || !component) {
-        throw new Error(`Invalid route config: path must be a string and component is required.
-${JSON.stringify(routeConfig)}`);
-    }
-    if (!subroutes) {
-        res.routesPaths.push(routePath);
-    }
-    const routeHash = (0, utils_1.simpleHash)(JSON.stringify(routeConfig), 3);
-    res.routesChunkNames[`${routePath}-${routeHash}`] = {
-        // Avoid clash with a prop called "component"
-        ...genChunkNames({ __comp: component }, 'component', component, res),
-        ...(context &&
-            genChunkNames({ __context: context }, 'context', routePath, res)),
-        ...genChunkNames(modules, 'module', routePath, res),
-    };
-    return serializeRouteConfig({
-        routePath: routePath.replace(/'/g, "\\'"),
-        routeHash,
-        subroutesCodeStrings: subroutes?.map((r) => genRouteCode(r, res)),
-        exact,
-        props,
-    });
-}
 /**
  * Old stuff
  * As far as I understand, this is what permits to SSG the 404.html file
@@ -167,39 +45,10 @@ ${JSON.stringify(routeConfig)}`);
  * The extension probably permits to avoid emitting "/404/index.html"
  */
 const NotFoundRoutePath = '/404.html';
-/**
- * Routes are prepared into three temp files:
- *
- * - `routesConfig`, the route config passed to react-router. This file is kept
- * minimal, because it can't be code-splitted.
- * - `routesChunkNames`, a mapping from route paths (hashed) to code-splitted
- * chunk names.
- * - `registry`, a mapping from chunk names to options for react-loadable.
- */
-function loadRoutes(routeConfigs, baseUrl, onDuplicateRoutes) {
-    handleDuplicateRoutes(routeConfigs, onDuplicateRoutes);
-    const res = {
-        // To be written by `genRouteCode`
-        routesConfig: '',
-        routesChunkNames: {},
-        registry: {},
-        routesPaths: [(0, utils_1.normalizeUrl)([baseUrl, NotFoundRoutePath])],
-    };
-    // `genRouteCode` would mutate `res`
-    const routeConfigSerialized = routeConfigs
-        .map((r) => genRouteCode(r, res))
-        .join(',\n');
-    res.routesConfig = `import React from 'react';
-import ComponentCreator from '@docusaurus/ComponentCreator';
-
-export default [
-${indent(routeConfigSerialized)},
-  {
-    path: '*',
-    component: ComponentCreator('*'),
-  },
-];
-`;
-    return res;
+function getRoutesPaths(routeConfigs, baseUrl) {
+    return [
+        (0, utils_1.normalizeUrl)([baseUrl, NotFoundRoutePath]),
+        ...getAllFinalRoutes(routeConfigs).map((r) => r.path),
+    ];
 }
-exports.loadRoutes = loadRoutes;
+exports.getRoutesPaths = getRoutesPaths;

package/lib/server/{index.d.ts → site.d.ts}

@@ -5,7 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { LoadContext, Props } from '@docusaurus/types';
-export type LoadContextOptions = {
+import type { PluginIdentifier } from '@docusaurus/types/src/plugin';
+export type LoadContextParams = {
     /** Usually the CWD; can be overridden with command argument. */
     siteDir: string;
     /** Custom output directory. Can be customized with `--out-dir` option */
@@ -22,17 +23,24 @@ export type LoadContextOptions = {
      */
     localizePath?: boolean;
 };
+export type LoadSiteParams = LoadContextParams;
+export type Site = {
+    props: Props;
+    params: LoadSiteParams;
+};
 /**
- * Loading context is the very first step in site building. Its options are
+ * Loading context is the very first step in site building. Its params are
  * directly acquired from CLI options. It mainly loads `siteConfig` and the i18n
  * context (which includes code translations). The `LoadContext` will be passed
  * to plugin constructors.
  */
-export declare function loadContext(options: LoadContextOptions): Promise<LoadContext>;
+export declare function loadContext(params: LoadContextParams): Promise<LoadContext>;
 /**
  * This is the crux of the Docusaurus server-side. It reads everything it needs—
  * code translations, config file, plugin modules... Plugins then use their
  * lifecycles to generate content and other data. It is side-effect-ful because
  * it generates temp files in the `.docusaurus` folder for the bundler.
  */
-export declare function load(options: LoadContextOptions): Promise<Props>;
+export declare function loadSite(params: LoadContextParams): Promise<Site>;
+export declare function reloadSite(site: Site): Promise<Site>;
+export declare function reloadSitePlugin(site: Site, pluginIdentifier: PluginIdentifier): Promise<Site>;

package/lib/server/site.js

@@ -0,0 +1,167 @@
+"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.reloadSitePlugin = exports.reloadSite = exports.loadSite = exports.loadContext = void 0;
+const tslib_1 = require("tslib");
+const path_1 = tslib_1.__importDefault(require("path"));
+const utils_1 = require("@docusaurus/utils");
+const combine_promises_1 = tslib_1.__importDefault(require("combine-promises"));
+const config_1 = require("./config");
+const clientModules_1 = require("./clientModules");
+const plugins_1 = require("./plugins/plugins");
+const htmlTags_1 = require("./htmlTags");
+const siteMetadata_1 = require("./siteMetadata");
+const i18n_1 = require("./i18n");
+const translations_1 = require("./translations/translations");
+const utils_2 = require("../utils");
+const codegen_1 = require("./codegen/codegen");
+const routes_1 = require("./routes");
+/**
+ * Loading context is the very first step in site building. Its params are
+ * directly acquired from CLI options. It mainly loads `siteConfig` and the i18n
+ * context (which includes code translations). The `LoadContext` will be passed
+ * to plugin constructors.
+ */
+async function loadContext(params) {
+    const { siteDir, outDir: baseOutDir = utils_1.DEFAULT_BUILD_DIR_NAME, locale, config: customConfigFilePath, } = params;
+    const generatedFilesDir = path_1.default.resolve(siteDir, utils_1.GENERATED_FILES_DIR_NAME);
+    const { siteConfig: initialSiteConfig, siteConfigPath } = await (0, config_1.loadSiteConfig)({
+        siteDir,
+        customConfigFilePath,
+    });
+    const i18n = await (0, i18n_1.loadI18n)(initialSiteConfig, { locale });
+    const baseUrl = (0, utils_1.localizePath)({
+        path: initialSiteConfig.baseUrl,
+        i18n,
+        options: params,
+        pathType: 'url',
+    });
+    const outDir = (0, utils_1.localizePath)({
+        path: path_1.default.resolve(siteDir, baseOutDir),
+        i18n,
+        options: params,
+        pathType: 'fs',
+    });
+    const localizationDir = path_1.default.resolve(siteDir, i18n.path, i18n.localeConfigs[i18n.currentLocale].path);
+    const siteConfig = { ...initialSiteConfig, baseUrl };
+    const codeTranslations = await (0, translations_1.loadSiteCodeTranslations)({ localizationDir });
+    return {
+        siteDir,
+        generatedFilesDir,
+        localizationDir,
+        siteConfig,
+        siteConfigPath,
+        outDir,
+        baseUrl,
+        i18n,
+        codeTranslations,
+    };
+}
+exports.loadContext = loadContext;
+async function createSiteProps(params) {
+    const { plugins, routes, context } = params;
+    const { generatedFilesDir, siteDir, siteConfig, siteConfigPath, outDir, baseUrl, i18n, localizationDir, codeTranslations: siteCodeTranslations, } = context;
+    const { headTags, preBodyTags, postBodyTags } = (0, htmlTags_1.loadHtmlTags)(plugins);
+    const { codeTranslations, siteMetadata } = await (0, combine_promises_1.default)({
+        // TODO code translations should be loaded as part of LoadedPlugin?
+        codeTranslations: utils_2.PerfLogger.async('Load - loadCodeTranslations', async () => ({
+            ...(await (0, translations_1.getPluginsDefaultCodeTranslationMessages)(plugins)),
+            ...siteCodeTranslations,
+        })),
+        siteMetadata: utils_2.PerfLogger.async('Load - loadSiteMetadata', () => (0, siteMetadata_1.loadSiteMetadata)({ plugins, siteDir })),
+    });
+    (0, routes_1.handleDuplicateRoutes)(routes, siteConfig.onDuplicateRoutes);
+    const routesPaths = (0, routes_1.getRoutesPaths)(routes, baseUrl);
+    return {
+        siteConfig,
+        siteConfigPath,
+        siteMetadata,
+        siteDir,
+        outDir,
+        baseUrl,
+        i18n,
+        localizationDir,
+        generatedFilesDir,
+        routes,
+        routesPaths,
+        plugins,
+        headTags,
+        preBodyTags,
+        postBodyTags,
+        codeTranslations,
+    };
+}
+// TODO global data should be part of site props?
+async function createSiteFiles({ site, globalData, }) {
+    return utils_2.PerfLogger.async('Load - createSiteFiles', async () => {
+        const { props: { plugins, generatedFilesDir, siteConfig, siteMetadata, i18n, codeTranslations, routes, baseUrl, }, } = site;
+        const clientModules = (0, clientModules_1.loadClientModules)(plugins);
+        await (0, codegen_1.generateSiteFiles)({
+            generatedFilesDir,
+            clientModules,
+            siteConfig,
+            siteMetadata,
+            i18n,
+            codeTranslations,
+            globalData,
+            routes,
+            baseUrl,
+        });
+    });
+}
+/**
+ * This is the crux of the Docusaurus server-side. It reads everything it needs—
+ * code translations, config file, plugin modules... Plugins then use their
+ * lifecycles to generate content and other data. It is side-effect-ful because
+ * it generates temp files in the `.docusaurus` folder for the bundler.
+ */
+async function loadSite(params) {
+    utils_2.PerfLogger.start('Load - loadContext');
+    const context = await loadContext(params);
+    utils_2.PerfLogger.end('Load - loadContext');
+    utils_2.PerfLogger.start('Load - loadPlugins');
+    const { plugins, routes, globalData } = await (0, plugins_1.loadPlugins)(context);
+    utils_2.PerfLogger.end('Load - loadPlugins');
+    const props = await createSiteProps({ plugins, routes, globalData, context });
+    const site = { props, params };
+    await createSiteFiles({
+        site,
+        globalData,
+    });
+    return site;
+}
+exports.loadSite = loadSite;
+async function reloadSite(site) {
+    // TODO this can be optimized, for example:
+    //  - plugins loading same data as before should not recreate routes/bundles
+    //  - codegen does not need to re-run if nothing changed
+    return loadSite(site.params);
+}
+exports.reloadSite = reloadSite;
+async function reloadSitePlugin(site, pluginIdentifier) {
+    console.log(`reloadSitePlugin ${pluginIdentifier.name}@${pluginIdentifier.id}`);
+    const { plugins, routes, globalData } = await (0, plugins_1.reloadPlugin)({
+        pluginIdentifier,
+        plugins: site.props.plugins,
+        context: site.props,
+    });
+    const newProps = await createSiteProps({
+        plugins,
+        routes,
+        globalData,
+        context: site.props, // Props extends Context
+    });
+    const newSite = {
+        props: newProps,
+        params: site.params,
+    };
+    // TODO optimize, bypass useless codegen if new site is similar to old site
+    await createSiteFiles({ site: newSite, globalData });
+    return newSite;
+}
+exports.reloadSitePlugin = reloadSitePlugin;

package/lib/server/translations/translations.d.ts

@@ -28,4 +28,7 @@ export declare function applyDefaultCodeTranslations({ extractedCodeTranslations
     extractedCodeTranslations: TranslationFileContent;
     defaultCodeMessages: CodeTranslations;
 }): TranslationFileContent;
+export declare function loadSiteCodeTranslations({ localizationDir, }: {
+    localizationDir: string;
+}): Promise<CodeTranslations>;
 export {};

package/lib/server/translations/translations.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.applyDefaultCodeTranslations = exports.getPluginsDefaultCodeTranslationMessages = exports.localizePluginTranslationFile = exports.writePluginTranslations = exports.writeCodeTranslations = exports.readCodeTranslationFileContent = void 0;
+exports.loadSiteCodeTranslations = exports.applyDefaultCodeTranslations = exports.getPluginsDefaultCodeTranslationMessages = exports.localizePluginTranslationFile = exports.writePluginTranslations = exports.writeCodeTranslations = exports.readCodeTranslationFileContent = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
@@ -162,3 +162,9 @@ Please report this Docusaurus issue. name=${unusedDefaultCodeMessages}`;
     }));
 }
 exports.applyDefaultCodeTranslations = applyDefaultCodeTranslations;
+async function loadSiteCodeTranslations({ localizationDir, }) {
+    const codeTranslationFileContent = (await readCodeTranslationFileContent({ localizationDir })) ?? {};
+    // We only need key->message for code translations
+    return lodash_1.default.mapValues(codeTranslationFileContent, (value) => value.message);
+}
+exports.loadSiteCodeTranslations = loadSiteCodeTranslations;

package/lib/server/utils.d.ts

@@ -5,6 +5,4 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { Globby } from '@docusaurus/utils';
-import type { RouteConfig } from '@docusaurus/types';
-export declare function getAllFinalRoutes(routeConfig: RouteConfig[]): RouteConfig[];
 export declare function safeGlobby(patterns: string[], options?: Globby.GlobbyOptions): Promise<string[]>;

package/lib/server/utils.js

@@ -6,18 +6,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.safeGlobby = exports.getAllFinalRoutes = void 0;
+exports.safeGlobby = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const utils_1 = require("@docusaurus/utils");
-// Recursively get the final routes (routes with no subroutes)
-function getAllFinalRoutes(routeConfig) {
-    function getFinalRoutes(route) {
-        return route.routes ? route.routes.flatMap(getFinalRoutes) : [route];
-    }
-    return routeConfig.flatMap(getFinalRoutes);
-}
-exports.getAllFinalRoutes = getAllFinalRoutes;
 // Globby that fix Windows path patterns
 // See https://github.com/facebook/docusaurus/pull/4222#issuecomment-795517329
 async function safeGlobby(patterns, options) {

package/lib/utils.d.ts

@@ -3,6 +3,7 @@ type PerfLoggerAPI = {
     start: (label: string) => void;
     end: (label: string) => void;
     log: (message: string) => void;
+    async: <Result>(label: string, asyncFn: () => Result | Promise<Result>) => Promise<Result>;
 };
 export declare const PerfLogger: PerfLoggerAPI;
 export {};

package/lib/utils.js

@@ -19,13 +19,24 @@ function createPerfLogger() {
             start: noop,
             end: noop,
             log: noop,
+            async: async (_label, asyncFn) => asyncFn(),
         };
     }
     const prefix = logger_1.default.yellow(`[PERF] `);
+    const start = (label) => console.time(prefix + label);
+    const end = (label) => console.timeEnd(prefix + label);
+    const log = (label) => console.log(prefix + label);
+    const async = async (label, asyncFn) => {
+        start(label);
+        const result = await asyncFn();
+        end(label);
+        return result;
+    };
     return {
-        start: (label) => console.time(prefix + label),
-        end: (label) => console.timeEnd(prefix + label),
-        log: (label) => console.log(prefix + label),
+        start,
+        end,
+        log,
+        async,
     };
 }
 exports.PerfLogger = createPerfLogger();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docusaurus/core",
   "description": "Easy to Maintain Open Source Documentation Websites",
-  "version": "0.0.0-5857",
+  "version": "0.0.0-5860",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -43,13 +43,13 @@
     "@babel/runtime": "^7.22.6",
     "@babel/runtime-corejs3": "^7.22.6",
     "@babel/traverse": "^7.22.8",
-    "@docusaurus/cssnano-preset": "0.0.0-5857",
-    "@docusaurus/logger": "0.0.0-5857",
-    "@docusaurus/mdx-loader": "0.0.0-5857",
+    "@docusaurus/cssnano-preset": "0.0.0-5860",
+    "@docusaurus/logger": "0.0.0-5860",
+    "@docusaurus/mdx-loader": "0.0.0-5860",
     "@docusaurus/react-loadable": "5.5.2",
-    "@docusaurus/utils": "0.0.0-5857",
-    "@docusaurus/utils-common": "0.0.0-5857",
-    "@docusaurus/utils-validation": "0.0.0-5857",
+    "@docusaurus/utils": "0.0.0-5860",
+    "@docusaurus/utils-common": "0.0.0-5860",
+    "@docusaurus/utils-validation": "0.0.0-5860",
     "@svgr/webpack": "^6.5.1",
     "autoprefixer": "^10.4.14",
     "babel-loader": "^9.1.3",
@@ -105,8 +105,8 @@
     "webpackbar": "^5.0.2"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-5857",
-    "@docusaurus/types": "0.0.0-5857",
+    "@docusaurus/module-type-aliases": "0.0.0-5860",
+    "@docusaurus/types": "0.0.0-5860",
     "@types/detect-port": "^1.3.3",
     "@types/react-dom": "^18.2.7",
     "@types/react-router-config": "^5.0.7",
@@ -125,5 +125,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "d239a09abb8c6ea81bb7b5382a594ecf96c4a164"
+  "gitHead": "dc91f3f6c8cf54d51409a24d823db17eee03a01a"
 }