feat(core): allow plugins to self-disable by returning null (#10286)

packages/docusaurus-plugin-client-redirects/src/index.ts

@@ -21,15 +21,15 @@ const PluginName = 'docusaurus-plugin-client-redirects';
 export default function pluginClientRedirectsPages(
  context: LoadContext,
  options: PluginOptions,
-): Plugin<void> {
+): Plugin<void> | null {
  const {trailingSlash} = context.siteConfig;
  const router = context.siteConfig.future.experimental_router;
 
  if (router === 'hash') {
  logger.warn(
  `${PluginName} does not support the Hash Router and will be disabled.`,
  );
- return {name: PluginName};
+ return null;
  }
 
  return {

packages/docusaurus-plugin-google-analytics/src/index.ts

@@ -18,21 +18,21 @@ import type {PluginOptions, Options} from './options';
 export default function pluginGoogleAnalytics(
  context: LoadContext,
  options: PluginOptions,
-): Plugin {
+): Plugin | null {
+ if (process.env.NODE_ENV !== 'production') {
+ return null;
+ }
+
  const {trackingID, anonymizeIP} = options;
- const isProd = process.env.NODE_ENV === 'production';
 
  return {
  name: 'docusaurus-plugin-google-analytics',
 
  getClientModules() {
- return isProd ? ['./analytics'] : [];
+ return ['./analytics'];
  },
 
  injectHtmlTags() {
- if (!isProd) {
- return {};
- }
  return {
  headTags: [
  {

packages/docusaurus-plugin-google-gtag/src/index.ts

@@ -32,8 +32,10 @@ function createConfigSnippets({
 export default function pluginGoogleGtag(
  context: LoadContext,
  options: PluginOptions,
-): Plugin {
- const isProd = process.env.NODE_ENV === 'production';
+): Plugin | null {
+ if (process.env.NODE_ENV !== 'production') {
+ return null;
+ }
 
  const firstTrackingId = options.trackingID[0];
 
@@ -45,13 +47,10 @@ export default function pluginGoogleGtag(
  },
 
  getClientModules() {
- return isProd ? ['./gtag'] : [];
+ return ['./gtag'];
  },
 
  injectHtmlTags() {
- if (!isProd) {
- return {};
- }
  return {
  // Gtag includes GA by default, so we also preconnect to
  // google-analytics.

packages/docusaurus-plugin-google-tag-manager/src/index.ts

@@ -16,10 +16,12 @@ import type {PluginOptions, Options} from './options';
 export default function pluginGoogleAnalytics(
  context: LoadContext,
  options: PluginOptions,
-): Plugin {
- const {containerId} = options;
- const isProd = process.env.NODE_ENV === 'production';
+): Plugin | null {
+ if (process.env.NODE_ENV !== 'production') {
+ return null;
+ }
 
+ const {containerId} = options;
  return {
  name: 'docusaurus-plugin-google-tag-manager',
 
@@ -28,9 +30,6 @@ export default function pluginGoogleAnalytics(
  },
 
  injectHtmlTags() {
- if (!isProd) {
- return {};
- }
  return {
  preBodyTags: [
  {

packages/docusaurus-plugin-pwa/src/index.ts

@@ -19,8 +19,6 @@ import type {PluginOptions} from '@docusaurus/plugin-pwa';
 
 const PluginName = 'docusaurus-plugin-pwa';
 
-const isProd = process.env.NODE_ENV === 'production';
-
 function getSWBabelLoader() {
  return {
  loader: 'babel-loader',
@@ -45,12 +43,21 @@ function getSWBabelLoader() {
 export default function pluginPWA(
  context: LoadContext,
  options: PluginOptions,
-): Plugin<void> {
+): Plugin<void> | null {
+ if (process.env.NODE_ENV !== 'production') {
+ return null;
+ }
+ if (context.siteConfig.future.experimental_router === 'hash') {
+ logger.warn(
+ `${PluginName} does not support the Hash Router and will be disabled.`,
+ );
+ return null;
+ }
+
  const {
  outDir,
  baseUrl,
  i18n: {currentLocale},
- siteConfig,
  } = context;
  const {
  debug,
@@ -61,13 +68,6 @@ export default function pluginPWA(
  swRegister,
  } = options;
 
- if (siteConfig.future.experimental_router === 'hash') {
- logger.warn(
- `${PluginName} does not support the Hash Router and will be disabled.`,
- );
- return {name: PluginName};
- }
-
  return {
  name: PluginName,
 
@@ -79,7 +79,7 @@ export default function pluginPWA(
  },
 
  getClientModules() {
- return isProd && swRegister ? [swRegister] : [];
+ return swRegister ? [swRegister] : [];
  },
 
  getDefaultCodeTranslationMessages() {
@@ -90,10 +90,6 @@ export default function pluginPWA(
  },
 
  configureWebpack(config) {
- if (!isProd) {
- return {};
- }
-
  return {
  plugins: [
  new webpack.EnvironmentPlugin({
@@ -111,37 +107,31 @@ export default function pluginPWA(
 
  injectHtmlTags() {
  const headTags: HtmlTags = [];
- if (isProd) {
- pwaHead.forEach(({tagName, ...attributes}) => {
- (['href', 'content'] as const).forEach((attribute) => {
- const attributeValue = attributes[attribute];
-
- if (!attributeValue) {
- return;
- }
-
- const attributePath =
- !!path.extname(attributeValue) && attributeValue;
-
- if (attributePath && !attributePath.startsWith(baseUrl)) {
- attributes[attribute] = normalizeUrl([baseUrl, attributeValue]);
- }
- });
-
- return headTags.push({
- tagName,
- attributes,
- });
+ pwaHead.forEach(({tagName, ...attributes}) => {
+ (['href', 'content'] as const).forEach((attribute) => {
+ const attributeValue = attributes[attribute];
+
+ if (!attributeValue) {
+ return;
+ }
+
+ const attributePath =
+ !!path.extname(attributeValue) && attributeValue;
+
+ if (attributePath && !attributePath.startsWith(baseUrl)) {
+ attributes[attribute] = normalizeUrl([baseUrl, attributeValue]);
+ }
+ });
+
+ return headTags.push({
+ tagName,
+ attributes,
  });
- }
+ });
  return {headTags};
  },
 
  async postBuild(props) {
- if (!isProd) {
- return;
- }
-
  const swSourceFileTest = /\.m?js$/;
 
  const swWebpackConfig: Configuration = {

packages/docusaurus-plugin-sitemap/src/index.ts

@@ -17,12 +17,12 @@ const PluginName = 'docusaurus-plugin-sitemap';
 export default function pluginSitemap(
  context: LoadContext,
  options: PluginOptions,
-): Plugin<void> {
+): Plugin<void> | null {
  if (context.siteConfig.future.experimental_router === 'hash') {
  logger.warn(
  `${PluginName} does not support the Hash Router and will be disabled.`,
  );
- return {name: PluginName};
+ return null;
  }
 
  return {

packages/docusaurus-plugin-vercel-analytics/src/index.ts

@@ -11,14 +11,15 @@ import type {PluginOptions, Options} from './options';
 export default function pluginVercelAnalytics(
  context: LoadContext,
  options: PluginOptions,
-): Plugin {
- const isProd = process.env.NODE_ENV === 'production';
-
+): Plugin | null {
+ if (process.env.NODE_ENV !== 'production') {
+ return null;
+ }
  return {
  name: 'docusaurus-plugin-vercel-analytics',
 
  getClientModules() {
- return isProd ? ['./analytics'] : [];
+ return ['./analytics'];
  },
 
  contentLoaded({actions}) {

packages/docusaurus-types/src/plugin.d.ts

@@ -191,7 +191,10 @@ export type LoadedPlugin = InitializedPlugin & {
 export type PluginModule<Content = unknown> = {
  (context: LoadContext, options: unknown):
  | Plugin<Content>
- | Promise<Plugin<Content>>;
+ | Promise<Plugin<Content>>
+ | null
+ | Promise<null>;
+
  validateOptions?: <T, U>(data: OptionValidationContext<T, U>) => U;
  validateThemeConfig?: <T>(data: ThemeConfigValidationContext<T>) => T;
 

packages/docusaurus/src/commands/swizzle/context.ts

@@ -6,22 +6,41 @@
  */
 
 import {loadContext} from '../../server/site';
-import {initPlugins} from '../../server/plugins/init';
+import {initPluginsConfigs} from '../../server/plugins/init';
 import {loadPluginConfigs} from '../../server/plugins/configs';
-import type {SwizzleCLIOptions, SwizzleContext} from './common';
+import type {SwizzleCLIOptions, SwizzleContext, SwizzlePlugin} from './common';
+import type {LoadContext} from '@docusaurus/types';
+
+async function getSwizzlePlugins(
+ context: LoadContext,
+): Promise<SwizzlePlugin[]> {
+ const pluginConfigs = await loadPluginConfigs(context);
+ const pluginConfigInitResults = await 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,
+ },
+ ];
+ });
+}
 
 export async function initSwizzleContext(
  siteDir: string,
  options: SwizzleCLIOptions,
 ): Promise<SwizzleContext> {
  const context = await loadContext({siteDir, config: options.config});
- const plugins = await initPlugins(context);
- const pluginConfigs = await loadPluginConfigs(context);
-
  return {
- plugins: plugins.map((plugin, pluginIndex) => ({
- plugin: pluginConfigs[pluginIndex]!,
- instance: plugin,
- })),
+ plugins: await getSwizzlePlugins(context),
  };
 }

packages/docusaurus/src/server/plugins/__tests__/init.test.ts

@@ -24,7 +24,7 @@ async function loadSite(
 describe('initPlugins', () => {
  it('parses plugins correctly and loads them in correct order', async () => {
  const {context, plugins} = await loadSite('site-with-plugin');
- expect(context.siteConfig.plugins).toHaveLength(6);
+ expect(context.siteConfig.plugins).toHaveLength(7);
  expect(plugins).toHaveLength(10);
 
  expect(plugins[0]!.name).toBe('preset-plugin1');
@@ -85,4 +85,13 @@ describe('initPlugins', () => {
  Note that even inline/anonymous plugin functions require a 'name' property."
  `);
  });
+
+ it('throws user-friendly error message for plugins returning undefined', async () => {
+ await expect(() => loadSite('site-with-undefined-plugin')).rejects
+ .toThrowErrorMatchingInlineSnapshot(`
+ "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'"
+ `);
+ });
 });