@docusaurus/core 0.0.0-4811 → 0.0.0-4814

package/lib/client/exports/ComponentCreator.js

@@ -16,66 +16,86 @@ export default function ComponentCreator(path, hash) {
     if (path === '*') {
         return Loadable({
             loading: Loading,
-            loader: async () => {
-                const NotFound = (await import('@theme/NotFound')).default;
-                return (props) => (
-                // Is there a better API for this?
-                <RouteContextProvider value={{ plugin: { name: 'native', id: 'default' } }}>
+            loader: () => import('@theme/NotFound').then(({ default: NotFound }) => (props) => (<RouteContextProvider 
+            // Do we want a better name than native-default?
+            value={{ plugin: { name: 'native', id: 'default' } }}>
             <NotFound {...props}/>
-          </RouteContextProvider>);
-            },
+          </RouteContextProvider>)),
         });
     }
     const chunkNames = routesChunkNames[`${path}-${hash}`];
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const optsLoader = {};
-    const optsModules = [];
+    const loader = {};
+    const modules = [];
     const optsWebpack = [];
+    // A map from prop names to chunk names.
+    // e.g. Suppose the plugin added this as route:
+    //   { __comp: "...", prop: { foo: "..." }, items: ["...", "..."] }
+    // It will become:
+    //   { __comp: "...", "prop.foo": "...", "items.0": "...", "items.1": ... }
+    // Loadable.Map will _map_ over `loader` and load each key.
     const flatChunkNames = flat(chunkNames);
-    Object.entries(flatChunkNames).forEach(([key, chunkName]) => {
+    Object.entries(flatChunkNames).forEach(([keyPath, chunkName]) => {
         const chunkRegistry = registry[chunkName];
         if (chunkRegistry) {
             // eslint-disable-next-line prefer-destructuring
-            optsLoader[key] = chunkRegistry[0];
-            optsModules.push(chunkRegistry[1]);
+            loader[keyPath] = chunkRegistry[0];
+            modules.push(chunkRegistry[1]);
             optsWebpack.push(chunkRegistry[2]);
         }
     });
     return Loadable.Map({
         loading: Loading,
-        loader: optsLoader,
-        modules: optsModules,
+        loader,
+        modules,
         webpack: () => optsWebpack,
         render: (loaded, props) => {
-            // Clone the original object since we don't want to alter the original.
+            // `loaded` will be a map from key path (as returned from the flattened
+            // chunk names) to the modules loaded from the loaders. We now have to
+            // restore the chunk names' previous shape from this flat record.
+            // We do so by taking advantage of the existing `chunkNames` and replacing
+            // each chunk name with its loaded module, so we don't create another
+            // object from scratch.
             const loadedModules = JSON.parse(JSON.stringify(chunkNames));
-            Object.keys(loaded).forEach((key) => {
-                const newComp = loaded[key].default;
-                if (!newComp) {
+            Object.entries(loaded).forEach(([keyPath, loadedModule]) => {
+                // JSON modules are also loaded as `{ default: ... }` (`import()`
+                // semantics) but we just want to pass the actual value to props.
+                const chunk = loadedModule.default;
+                // One loaded chunk can only be one of two things: a module (props) or a
+                // component. Modules are always JSON, so `default` always exists. This
+                // could only happen with a user-defined component.
+                if (!chunk) {
                     throw new Error(`The page component at ${path} doesn't have a default export. This makes it impossible to render anything. Consider default-exporting a React component.`);
                 }
-                if (typeof newComp === 'object' || typeof newComp === 'function') {
-                    Object.keys(loaded[key])
+                // A module can be a primitive, for example, if the user stored a string
+                // as a prop. However, there seems to be a bug with swc-loader's CJS
+                // logic, in that it would load a JSON module with content "foo" as
+                // `{ default: "foo", 0: "f", 1: "o", 2: "o" }`. Just to be safe, we
+                // first make sure that the chunk is non-primitive.
+                if (typeof chunk === 'object' || typeof chunk === 'function') {
+                    Object.keys(loadedModule)
                         .filter((k) => k !== 'default')
                         .forEach((nonDefaultKey) => {
-                        newComp[nonDefaultKey] = loaded[key][nonDefaultKey];
+                        chunk[nonDefaultKey] = loadedModule[nonDefaultKey];
                     });
                 }
+                // We now have this chunk prepared. Go down the key path and replace the
+                // chunk name with the actual chunk.
                 let val = loadedModules;
-                const keyPath = key.split('.');
-                keyPath.slice(0, -1).forEach((k) => {
+                const keyPaths = keyPath.split('.');
+                keyPaths.slice(0, -1).forEach((k) => {
                     val = val[k];
                 });
-                val[keyPath[keyPath.length - 1]] = newComp;
+                val[keyPaths[keyPaths.length - 1]] = chunk;
             });
-            const Component = loadedModules.component;
-            delete loadedModules.component;
             /* eslint-disable no-underscore-dangle */
-            const routeContextModule = loadedModules.__routeContextModule;
-            delete loadedModules.__routeContextModule;
+            const Component = loadedModules.__comp;
+            delete loadedModules.__comp;
+            const routeContext = loadedModules.__context;
+            delete loadedModules.__context;
             /* eslint-enable no-underscore-dangle */
             // Is there any way to put this RouteContextProvider upper in the tree?
-            return (<RouteContextProvider value={routeContextModule}>
+            return (<RouteContextProvider value={routeContext}>
           <Component {...loadedModules} {...props}/>
         </RouteContextProvider>);
         },

package/lib/client/prefetch.js

@@ -4,20 +4,14 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-function support(feature) {
-    if (typeof document === 'undefined') {
-        return false;
-    }
-    const fakeLink = document.createElement('link');
+function supports(feature) {
     try {
-        if (fakeLink.relList && typeof fakeLink.relList.supports === 'function') {
-            return fakeLink.relList.supports(feature);
-        }
+        const fakeLink = document.createElement('link');
+        return fakeLink.relList?.supports?.(feature);
     }
     catch (err) {
         return false;
     }
-    return false;
 }
 function linkPrefetchStrategy(url) {
     return new Promise((resolve, reject) => {
@@ -51,7 +45,7 @@ function xhrPrefetchStrategy(url) {
         req.send(null);
     });
 }
-const supportedPrefetchStrategy = support('prefetch')
+const supportedPrefetchStrategy = supports('prefetch')
     ? linkPrefetchStrategy
     : xhrPrefetchStrategy;
 const preFetched = {};

package/lib/client/serverEntry.js

@@ -51,12 +51,12 @@ async function doRender(locals) {
     const location = routesLocation[locals.path];
     await preload(routes, location);
     const modules = new Set();
-    const context = {};
+    const routerContext = {};
     const helmetContext = {};
     const linksCollector = createStatefulLinksCollector();
     const appHtml = ReactDOMServer.renderToString(<Loadable.Capture report={(moduleName) => modules.add(moduleName)}>
       <HelmetProvider context={helmetContext}>
-        <StaticRouter location={location} context={context}>
+        <StaticRouter location={location} context={routerContext}>
           <LinksCollectorProvider linksCollector={linksCollector}>
             <App />
           </LinksCollectorProvider>

package/lib/server/index.js

@@ -76,9 +76,7 @@ async function load(options) {
     const { siteDir } = options;
     const context = await loadContext(options);
     const { generatedFilesDir, siteConfig, siteConfigPath, outDir, baseUrl, i18n, ssrTemplate, codeTranslations: siteCodeTranslations, } = context;
-    const { plugins, pluginsRouteConfigs, globalData, themeConfigTranslated } = await (0, plugins_1.loadPlugins)(context);
-    // Side-effect to replace the untranslated themeConfig by the translated one
-    context.siteConfig.themeConfig = themeConfigTranslated;
+    const { plugins, pluginsRouteConfigs, globalData } = await (0, plugins_1.loadPlugins)(context);
     const clientModules = (0, clientModules_1.loadClientModules)(plugins);
     const { headTags, preBodyTags, postBodyTags } = (0, htmlTags_1.loadHtmlTags)(plugins);
     const { registry, routesChunkNames, routesConfig, routesPaths } = await (0, routes_1.loadRoutes)(pluginsRouteConfigs, baseUrl, siteConfig.onDuplicateRoutes);

package/lib/server/plugins/index.d.ts

@@ -4,15 +4,15 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { LoadContext, RouteConfig, GlobalData, ThemeConfig, LoadedPlugin } from '@docusaurus/types';
+import type { LoadContext, RouteConfig, GlobalData, LoadedPlugin } from '@docusaurus/types';
 /**
  * Initializes the plugins, runs `loadContent`, `translateContent`,
  * `contentLoaded`, and `translateThemeConfig`. Because `contentLoaded` is
- * side-effect-ful (it generates temp files), so is this function.
+ * side-effect-ful (it generates temp files), so is this function. This function
+ * would also mutate `context.siteConfig.themeConfig` to translate it.
  */
 export declare function loadPlugins(context: LoadContext): Promise<{
     plugins: LoadedPlugin[];
     pluginsRouteConfigs: RouteConfig[];
     globalData: GlobalData;
-    themeConfigTranslated: ThemeConfig;
 }>;

package/lib/server/plugins/index.js

@@ -19,7 +19,8 @@ const routeConfig_1 = require("./routeConfig");
 /**
  * Initializes the plugins, runs `loadContent`, `translateContent`,
  * `contentLoaded`, and `translateThemeConfig`. Because `contentLoaded` is
- * side-effect-ful (it generates temp files), so is this function.
+ * side-effect-ful (it generates temp files), so is this function. This function
+ * would also mutate `context.siteConfig.themeConfig` to translate it.
  */
 async function loadPlugins(context) {
     // 1. Plugin Lifecycle - Initialization/Constructor.
@@ -29,24 +30,27 @@ async function loadPlugins(context) {
     // Currently plugins run lifecycle methods in parallel and are not
     // order-dependent. We could change this in future if there are plugins which
     // need to run in certain order or depend on others for data.
+    // This would also translate theme config and content upfront, given the
+    // translation files that the plugin declares.
     const loadedPlugins = await Promise.all(plugins.map(async (plugin) => {
         const content = await plugin.loadContent?.();
-        return { ...plugin, content };
-    }));
-    const contentLoadedTranslatedPlugins = await Promise.all(loadedPlugins.map(async (plugin) => {
-        const translationFiles = (await plugin?.getTranslationFiles?.({
-            content: plugin.content,
-        })) ?? [];
-        const localizedTranslationFiles = await Promise.all(translationFiles.map((translationFile) => (0, translations_1.localizePluginTranslationFile)({
+        const rawTranslationFiles = (await plugin?.getTranslationFiles?.({ content })) ?? [];
+        const translationFiles = await Promise.all(rawTranslationFiles.map((translationFile) => (0, translations_1.localizePluginTranslationFile)({
             locale: context.i18n.currentLocale,
             siteDir: context.siteDir,
             translationFile,
             plugin,
         })));
-        return {
-            ...plugin,
-            translationFiles: localizedTranslationFiles,
-        };
+        const translatedContent = plugin.translateContent?.({ content, translationFiles }) ?? content;
+        const translatedThemeConfigSlice = plugin.translateThemeConfig?.({
+            themeConfig: context.siteConfig.themeConfig,
+            translationFiles,
+        });
+        // Side-effect to merge theme config translations. A plugin should only
+        // translate its own slice of theme config and should make no assumptions
+        // about other plugins' keys, so this is safe to run in parallel.
+        Object.assign(context.siteConfig.themeConfig, translatedThemeConfigSlice);
+        return { ...plugin, content: translatedContent };
     }));
     const allContent = lodash_1.default.chain(loadedPlugins)
         .groupBy((item) => item.name)
@@ -58,7 +62,7 @@ async function loadPlugins(context) {
     // 3. Plugin Lifecycle - contentLoaded.
     const pluginsRouteConfigs = [];
     const globalData = {};
-    await Promise.all(contentLoadedTranslatedPlugins.map(async ({ content, translationFiles, ...plugin }) => {
+    await Promise.all(loadedPlugins.map(async ({ content, ...plugin }) => {
         if (!plugin.contentLoaded) {
             return;
         }
@@ -81,7 +85,7 @@ async function loadPlugins(context) {
                     ...finalRouteConfig,
                     modules: {
                         ...finalRouteConfig.modules,
-                        __routeContextModule: pluginRouteContextModulePath,
+                        __context: pluginRouteContextModulePath,
                     },
                 });
             },
@@ -96,43 +100,21 @@ async function loadPlugins(context) {
                 globalData[plugin.name][pluginId] = data;
             },
         };
-        const translatedContent = plugin.translateContent?.({ content, translationFiles }) ?? content;
-        await plugin.contentLoaded({
-            content: translatedContent,
-            actions,
-            allContent,
-        });
+        await plugin.contentLoaded({ content, actions, allContent });
     }));
     // 4. Plugin Lifecycle - routesLoaded.
-    await Promise.all(contentLoadedTranslatedPlugins.map(async (plugin) => {
+    await Promise.all(loadedPlugins.map(async (plugin) => {
         if (!plugin.routesLoaded) {
             return;
         }
-        // TODO remove this deprecated lifecycle soon
-        // deprecated since alpha-60
-        // TODO, 1 user reported usage of this lifecycle! https://github.com/facebook/docusaurus/issues/3918
+        // TODO alpha-60: remove this deprecated lifecycle soon
+        // 1 user reported usage of this lifecycle: https://github.com/facebook/docusaurus/issues/3918
         logger_1.default.error `Plugin code=${'routesLoaded'} lifecycle is deprecated. If you think we should keep this lifecycle, please report here: url=${'https://github.com/facebook/docusaurus/issues/3918'}`;
         await plugin.routesLoaded(pluginsRouteConfigs);
     }));
     // Sort the route config. This ensures that route with nested
     // routes are always placed last.
     (0, routeConfig_1.sortConfig)(pluginsRouteConfigs, context.siteConfig.baseUrl);
-    // Apply each plugin one after the other to translate the theme config
-    const themeConfigTranslated = contentLoadedTranslatedPlugins.reduce((currentThemeConfig, plugin) => {
-        const translatedThemeConfigSlice = plugin.translateThemeConfig?.({
-            themeConfig: currentThemeConfig,
-            translationFiles: plugin.translationFiles,
-        });
-        return {
-            ...currentThemeConfig,
-            ...translatedThemeConfigSlice,
-        };
-    }, context.siteConfig.themeConfig);
-    return {
-        plugins: loadedPlugins,
-        pluginsRouteConfigs,
-        globalData,
-        themeConfigTranslated,
-    };
+    return { plugins: loadedPlugins, pluginsRouteConfigs, globalData };
 }
 exports.loadPlugins = loadPlugins;

package/lib/server/routes.js

@@ -95,7 +95,10 @@ const isModule = (value) => typeof value === 'string' ||
     (typeof value === 'object' &&
         // eslint-disable-next-line no-underscore-dangle
         !!value?.__import);
-/** Takes a {@link Module} and returns the string path it represents. */
+/**
+ * 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;
@@ -144,7 +147,7 @@ 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 return the node's serialized form, and mutate `registry`,
+ * config node, it returns the node's serialized form, and mutates `registry`,
  * `routesPaths`, and `routesChunkNames` accordingly.
  */
 function genRouteCode(routeConfig, res) {
@@ -158,7 +161,8 @@ ${JSON.stringify(routeConfig)}`);
     }
     const routeHash = (0, utils_1.simpleHash)(JSON.stringify(routeConfig), 3);
     res.routesChunkNames[`${routePath}-${routeHash}`] = {
-        ...genChunkNames({ component }, 'component', component, res),
+        // Avoid clash with a prop called "component"
+        ...genChunkNames({ __comp: component }, 'component', component, res),
         ...genChunkNames(modules, 'module', routePath, res),
     };
     return serializeRouteConfig({
@@ -181,7 +185,7 @@ ${JSON.stringify(routeConfig)}`);
 async function loadRoutes(routeConfigs, baseUrl, onDuplicateRoutes) {
     handleDuplicateRoutes(routeConfigs, onDuplicateRoutes);
     const res = {
-        // To be written
+        // To be written by `genRouteCode`
         routesConfig: '',
         routesChunkNames: {},
         registry: {},

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docusaurus/core",
   "description": "Easy to Maintain Open Source Documentation Websites",
-  "version": "0.0.0-4811",
+  "version": "0.0.0-4814",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -41,13 +41,13 @@
     "@babel/runtime": "^7.17.8",
     "@babel/runtime-corejs3": "^7.17.8",
     "@babel/traverse": "^7.17.3",
-    "@docusaurus/cssnano-preset": "0.0.0-4811",
-    "@docusaurus/logger": "0.0.0-4811",
-    "@docusaurus/mdx-loader": "0.0.0-4811",
+    "@docusaurus/cssnano-preset": "0.0.0-4814",
+    "@docusaurus/logger": "0.0.0-4814",
+    "@docusaurus/mdx-loader": "0.0.0-4814",
     "@docusaurus/react-loadable": "5.5.2",
-    "@docusaurus/utils": "0.0.0-4811",
-    "@docusaurus/utils-common": "0.0.0-4811",
-    "@docusaurus/utils-validation": "0.0.0-4811",
+    "@docusaurus/utils": "0.0.0-4814",
+    "@docusaurus/utils-common": "0.0.0-4814",
+    "@docusaurus/utils-validation": "0.0.0-4814",
     "@slorber/static-site-generator-webpack-plugin": "^4.0.4",
     "@svgr/webpack": "^6.2.1",
     "autoprefixer": "^10.4.4",
@@ -105,8 +105,8 @@
     "webpackbar": "^5.0.2"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4811",
-    "@docusaurus/types": "0.0.0-4811",
+    "@docusaurus/module-type-aliases": "0.0.0-4814",
+    "@docusaurus/types": "0.0.0-4814",
     "@types/detect-port": "^1.3.2",
     "@types/nprogress": "^0.2.0",
     "@types/react-dom": "^17.0.14",
@@ -127,5 +127,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "f174c77967abd972ab9685ba682119b38c6ac55b"
+  "gitHead": "a9bcbaa758fc3daf0923d8b3c3bf0aa944c75d33"
 }