@docusaurus/core 0.0.0-5988 → 0.0.0-5993

package/lib/commands/swizzle/context.js

@@ -10,14 +10,26 @@ exports.initSwizzleContext = initSwizzleContext;
 const site_1 = require("../../server/site");
 const init_1 = require("../../server/plugins/init");
 const configs_1 = require("../../server/plugins/configs");
+async function getSwizzlePlugins(context) {
+    const pluginConfigs = await (0, configs_1.loadPluginConfigs)(context);
+    const pluginConfigInitResults = await (0, init_1.initPluginsConfigs)(context, pluginConfigs);
+    return pluginConfigInitResults.flatMap((initResult) => {
+        // Ignore self-disabling plugins returning null
+        if (initResult.plugin === null) {
+            return [];
+        }
+        return [
+            // TODO this is a bit confusing, need refactor
+            {
+                plugin: initResult.config,
+                instance: initResult.plugin,
+            },
+        ];
+    });
+}
 async function initSwizzleContext(siteDir, options) {
     const context = await (0, site_1.loadContext)({ siteDir, config: options.config });
-    const plugins = await (0, init_1.initPlugins)(context);
-    const pluginConfigs = await (0, configs_1.loadPluginConfigs)(context);
     return {
-        plugins: plugins.map((plugin, pluginIndex) => ({
-            plugin: pluginConfigs[pluginIndex],
-            instance: plugin,
-        })),
+        plugins: await getSwizzlePlugins(context),
     };
 }

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

@@ -4,9 +4,20 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import { type NormalizedPluginConfig } from './configs';
 import type { LoadContext, InitializedPlugin } from '@docusaurus/types';
+type PluginConfigInitResult = {
+    config: NormalizedPluginConfig;
+    plugin: InitializedPlugin | null;
+};
 /**
  * Runs the plugin constructors and returns their return values. It would load
  * plugin configs from `plugins`, `themes`, and `presets`.
  */
+export declare function initPluginsConfigs(context: LoadContext, pluginConfigs: NormalizedPluginConfig[]): Promise<PluginConfigInitResult[]>;
+/**
+ * Runs the plugin constructors and returns their return values
+ * for all the site context plugins that do not return null to self-disable.
+ */
 export declare function initPlugins(context: LoadContext): Promise<InitializedPlugin[]>;
+export {};

package/lib/server/plugins/init.js

@@ -6,6 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.initPluginsConfigs = initPluginsConfigs;
 exports.initPlugins = initPlugins;
 const tslib_1 = require("tslib");
 const module_1 = require("module");
@@ -31,15 +32,20 @@ function getThemeValidationFunction(normalizedPluginConfig) {
     }
     return normalizedPluginConfig.plugin.validateThemeConfig;
 }
+// This filters self-disabling plugins and returns only the initialized ones
+function onlyInitializedPlugins(initPluginsConfigsResults) {
+    return initPluginsConfigsResults
+        .map((results) => results.plugin)
+        .filter((p) => p !== null);
+}
 /**
  * Runs the plugin constructors and returns their return values. It would load
  * plugin configs from `plugins`, `themes`, and `presets`.
  */
-async function initPlugins(context) {
+async function initPluginsConfigs(context, pluginConfigs) {
     // We need to resolve plugins from the perspective of the site config, as if
     // we are using `require.resolve` on those module names.
     const pluginRequire = (0, module_1.createRequire)(context.siteConfigPath);
-    const pluginConfigs = await (0, configs_1.loadPluginConfigs)(context);
     async function doLoadPluginVersion(normalizedPluginConfig) {
         if (normalizedPluginConfig.pluginModule?.path) {
             const pluginPath = pluginRequire.resolve(normalizedPluginConfig.pluginModule.path);
@@ -76,23 +82,49 @@ async function initPlugins(context) {
         const pluginVersion = await doLoadPluginVersion(normalizedPluginConfig);
         const pluginOptions = doValidatePluginOptions(normalizedPluginConfig);
         // Side-effect: merge the normalized theme config in the original one
+        // Note: it's important to do this before calling the plugin constructor
+        // Example: the theme classic plugin will read siteConfig.themeConfig
         context.siteConfig.themeConfig = {
             ...context.siteConfig.themeConfig,
             ...doValidateThemeConfig(normalizedPluginConfig),
         };
         const pluginInstance = await normalizedPluginConfig.plugin(context, pluginOptions);
-        if (!pluginInstance.name) {
+        // Returning null has been explicitly allowed
+        // It's a way for plugins to self-disable depending on context
+        // See https://github.com/facebook/docusaurus/pull/10286
+        if (pluginInstance === null) {
+            return { config: normalizedPluginConfig, plugin: null };
+        }
+        if (pluginInstance === undefined) {
+            throw new Error(`A Docusaurus plugin returned 'undefined', which is forbidden.
+A plugin is expected to return an object having at least a 'name' property.
+If you want a plugin to self-disable depending on context/options, you can explicitly return 'null' instead of 'undefined'`);
+        }
+        if (!pluginInstance?.name) {
             throw new Error(`A Docusaurus plugin is missing a 'name' property.
 Note that even inline/anonymous plugin functions require a 'name' property.`);
         }
-        return {
+        const plugin = {
             ...pluginInstance,
             options: pluginOptions,
             version: pluginVersion,
             path: path_1.default.dirname(normalizedPluginConfig.entryPath),
         };
+        return {
+            config: normalizedPluginConfig,
+            plugin,
+        };
     }
-    const plugins = await Promise.all(pluginConfigs.map(initializePlugin));
-    (0, pluginIds_1.ensureUniquePluginInstanceIds)(plugins);
+    const plugins = (await Promise.all(pluginConfigs.map(initializePlugin))).filter((p) => p !== null);
+    (0, pluginIds_1.ensureUniquePluginInstanceIds)(onlyInitializedPlugins(plugins));
     return plugins;
 }
+/**
+ * Runs the plugin constructors and returns their return values
+ * for all the site context plugins that do not return null to self-disable.
+ */
+async function initPlugins(context) {
+    const pluginConfigs = await (0, configs_1.loadPluginConfigs)(context);
+    const initPluginsConfigsResults = await initPluginsConfigs(context, pluginConfigs);
+    return onlyInitializedPlugins(initPluginsConfigsResults);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docusaurus/core",
   "description": "Easy to Maintain Open Source Documentation Websites",
-  "version": "0.0.0-5988",
+  "version": "0.0.0-5993",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -43,12 +43,12 @@
     "@babel/runtime": "^7.22.6",
     "@babel/runtime-corejs3": "^7.22.6",
     "@babel/traverse": "^7.22.8",
-    "@docusaurus/cssnano-preset": "0.0.0-5988",
-    "@docusaurus/logger": "0.0.0-5988",
-    "@docusaurus/mdx-loader": "0.0.0-5988",
-    "@docusaurus/utils": "0.0.0-5988",
-    "@docusaurus/utils-common": "0.0.0-5988",
-    "@docusaurus/utils-validation": "0.0.0-5988",
+    "@docusaurus/cssnano-preset": "0.0.0-5993",
+    "@docusaurus/logger": "0.0.0-5993",
+    "@docusaurus/mdx-loader": "0.0.0-5993",
+    "@docusaurus/utils": "0.0.0-5993",
+    "@docusaurus/utils-common": "0.0.0-5993",
+    "@docusaurus/utils-validation": "0.0.0-5993",
     "autoprefixer": "^10.4.14",
     "babel-loader": "^9.1.3",
     "babel-plugin-dynamic-import-node": "^2.3.3",
@@ -103,8 +103,8 @@
     "webpackbar": "^5.0.2"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-5988",
-    "@docusaurus/types": "0.0.0-5988",
+    "@docusaurus/module-type-aliases": "0.0.0-5993",
+    "@docusaurus/types": "0.0.0-5993",
     "@total-typescript/shoehorn": "^0.1.2",
     "@types/detect-port": "^1.3.3",
     "@types/react-dom": "^18.2.7",
@@ -124,5 +124,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "d0fdafd91649c846567d686ec00d3ff6ae494556"
+  "gitHead": "0ad0160fc910803276cb4b5fe34254b7ec372bd4"
 }