feat(v2): better error message for invalid plugin config (#3979)

* test(v2): improve tests on validating plugins

* fix(v2): make schema for plugins stricter

* fix(v2): emit error if valid type of plugin is not found (#3934)

packages/docusaurus/src/server/__tests__/__snapshots__/configValidation.test.ts.snap

@@ -30,7 +30,37 @@ exports[`normalizeConfig should throw error if css doesn't have href 1`] = `
 "
 `;
 
-exports[`normalizeConfig should throw error if plugins is not array 1`] = `
+exports[`normalizeConfig should throw error if plugins is not a string and it's not an array #1 for the input of: [123] 1`] = `
+"\\"plugins[0]\\" does not match any of the allowed types
+"
+`;
+
+exports[`normalizeConfig should throw error if plugins is not a string and it's not an array #2 for the input of: [[Function anonymous]] 1`] = `
+"\\"plugins[0]\\" does not match any of the allowed types
+"
+`;
+
+exports[`normalizeConfig should throw error if plugins is not an array of [string, object][] #1 for the input of: [[Array]] 1`] = `
+"\\"plugins[0]\\" does not match any of the allowed types
+"
+`;
+
+exports[`normalizeConfig should throw error if plugins is not an array of [string, object][] #2 for the input of: [[Array]] 1`] = `
+"\\"plugins[0]\\" does not match any of the allowed types
+"
+`;
+
+exports[`normalizeConfig should throw error if plugins is not an array of [string, object][] #3 for the input of: [[Array]] 1`] = `
+"\\"plugins[0]\\" does not match any of the allowed types
+"
+`;
+
+exports[`normalizeConfig should throw error if plugins is not array for the input of: [Function anonymous] 1`] = `
+"\\"plugins\\" must be an array
+"
+`;
+
+exports[`normalizeConfig should throw error if plugins is not array for the input of: {} 1`] = `
 "\\"plugins\\" must be an array
 "
 `;

packages/docusaurus/src/server/__tests__/configValidation.test.ts

@@ -88,14 +88,79 @@ describe('normalizeConfig', () => {
     }).toThrowErrorMatchingSnapshot();
   });
 
-  test('should throw error if plugins is not array', () => {
+  test.each([
+    ['should throw error if plugins is not array', {}],
+    [
+      'should throw error if plugins is not array',
+      function () {
+        console.log('noop');
+      },
+    ],
+    [
+      "should throw error if plugins is not a string and it's not an array #1",
+      [123],
+    ],
+    [
+      "should throw error if plugins is not a string and it's not an array #2",
+      [
+        function () {
+          console.log('noop');
+        },
+      ],
+    ],
+    [
+      'should throw error if plugins is not an array of [string, object][] #1',
+      [['example/path', 'wrong parameter here']],
+    ],
+    [
+      'should throw error if plugins is not an array of [string, object][] #2',
+      [[{}, 'example/path']],
+    ],
+    [
+      'should throw error if plugins is not an array of [string, object][] #3',
+      [[{}, {}]],
+    ],
+  ])(`%s for the input of: %p`, (_message, plugins) => {
     expect(() => {
       normalizeConfig({
-        plugins: {},
+        plugins,
       });
     }).toThrowErrorMatchingSnapshot();
   });
 
+  test.each([
+    ['should accept [string] for plugins', ['plain/string']],
+    [
+      'should accept string[] for plugins',
+      ['plain/string', 'another/plain/string/path'],
+    ],
+    [
+      'should accept [string, object] for plugins',
+      [['plain/string', {it: 'should work'}]],
+    ],
+    [
+      'should accept [string, object][] for plugins',
+      [
+        ['plain/string', {it: 'should work'}],
+        ['this/should/work', {too: 'yes'}],
+      ],
+    ],
+    [
+      'should accept ([string, object]|string)[] for plugins',
+      [
+        'plain/string',
+        ['plain', {it: 'should work'}],
+        ['this/should/work', {too: 'yes'}],
+      ],
+    ],
+  ])(`%s for the input of: %p`, (_message, plugins) => {
+    expect(() => {
+      normalizeConfig({
+        plugins,
+      });
+    }).not.toThrowError();
+  });
+
   test('should throw error if themes is not array', () => {
     expect(() => {
       normalizeConfig({

packages/docusaurus/src/server/configValidation.ts

@@ -53,7 +53,9 @@ export const DEFAULT_CONFIG: Pick<
 
 const PluginSchema = Joi.alternatives().try(
   Joi.string(),
-  Joi.array().items(Joi.string().required(), Joi.object().required()).length(2),
+  Joi.array()
+    .ordered(Joi.string().required(), Joi.object().required())
+    .length(2),
   Joi.bool().equal(false), // In case of conditional adding of plugins.
 );
 

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

@@ -55,10 +55,15 @@ export default function initPlugins({
         pluginModuleImport = pluginItem;
       } else if (Array.isArray(pluginItem)) {
         [pluginModuleImport, pluginOptions = {}] = pluginItem;
+      } else {
+        throw new TypeError(`You supplied a wrong type of plugin.
+A plugin should be either string or [importPath: string, options?: object].
+
+For more information, visit https://v2.docusaurus.io/docs/using-plugins.`);
       }
 
       if (!pluginModuleImport) {
-        return null;
+        throw new Error('The path to the plugin is either undefined or null.');
       }
 
       // The pluginModuleImport value is any valid