feat(v2): add validation escape hatch (#3134)

* add isValidationDisabledEscapeHatch system

* add bug reporting hint for validation errors

* typo

.eslintrc.js

@@ -64,6 +64,7 @@ module.exports = {
     'jsx-a11y/click-events-have-key-events': WARNING,
     'jsx-a11y/no-noninteractive-element-interactions': WARNING,
     'no-console': OFF,
+    'no-else-return': OFF,
     'no-underscore-dangle': OFF,
     curly: [WARNING, 'all'],
     'react/jsx-closing-bracket-location': OFF, // Conflicts with Prettier.

packages/docusaurus/src/server/configValidation.ts

@@ -8,6 +8,10 @@
 import {DocusaurusConfig} from '@docusaurus/types';
 import {CONFIG_FILE_NAME} from '../constants';
 import Joi from '@hapi/joi';
+import {
+  isValidationDisabledEscapeHatch,
+  logValidationBugReportHint,
+} from './validationUtils';
 
 export const DEFAULT_CONFIG: Pick<
   DocusaurusConfig,
@@ -85,6 +89,12 @@ export function validateConfig(
     abortEarly: false,
   });
   if (error) {
+    logValidationBugReportHint();
+    if (isValidationDisabledEscapeHatch) {
+      console.error(error);
+      return config as DocusaurusConfig;
+    }
+
     const unknownFields = error.details.reduce((formattedError, err) => {
       if (err.type === 'object.unknown') {
         return `${formattedError}"${err.path}",`;

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

@@ -20,6 +20,10 @@ import {CONFIG_FILE_NAME} from '../../constants';
 import {getPluginVersion} from '../versions';
 import {ensureUniquePluginInstanceIds} from './pluginIds';
 import * as Joi from '@hapi/joi';
+import {
+  isValidationDisabledEscapeHatch,
+  logValidationBugReportHint,
+} from '../validationUtils';
 
 function pluginOptionsValidator<T>(
   schema: ValidationSchema<T>,
@@ -34,25 +38,37 @@ function pluginOptionsValidator<T>(
     convert: false,
   });
   if (error) {
-    throw error;
+    logValidationBugReportHint();
+    if (isValidationDisabledEscapeHatch) {
+      console.error(error);
+      return options;
+    } else {
+      throw error;
+    }
   }
   return value;
 }
 
 function themeConfigValidator<T>(
   schema: ValidationSchema<T>,
-  options: Partial<T>,
+  themeConfig: Partial<T>,
 ) {
   // A theme should only validate his "slice" of the full themeConfig,
   // not the whole object, so we allow unknown attributes to pass a theme validation
   const finalSchema = schema.unknown();
 
-  const {error, value} = finalSchema.validate(options, {
+  const {error, value} = finalSchema.validate(themeConfig, {
     convert: false,
   });
 
   if (error) {
-    throw error;
+    logValidationBugReportHint();
+    if (isValidationDisabledEscapeHatch) {
+      console.error(error);
+      return themeConfig;
+    } else {
+      throw error;
+    }
   }
   return value;
 }

packages/docusaurus/src/server/validationUtils.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+import chalk from 'chalk';
+
+// TODO temporary escape hatch for alpha-60: to be removed soon
+// Our validation schemas might be buggy at first
+// will permit users to bypass validation until we fix all validation errors
+// see for example: https://github.com/facebook/docusaurus/pull/3120
+// Undocumented on purpose, as we don't want users to keep using it over time
+// Maybe we'll make this escape hatch official some day, with a better api?
+export const isValidationDisabledEscapeHatch =
+  process.env.DISABLE_DOCUSAURUS_VALIDATION === 'true';
+
+isValidationDisabledEscapeHatch &&
+  console.error(
+    chalk.red(
+      'You should avoid using DISABLE_DOCUSAURUS_VALIDATION escape hatch, this will be removed',
+    ),
+  );
+
+export const logValidationBugReportHint = () => {
+  console.log(
+    `\n${chalk.red('A validation error occured.')}${chalk.cyanBright(
+      '\nThe validation system was added recently to Docusaurus as an attempt to avoid user configuration errors.' +
+        '\nWe may have made some mistakes.' +
+        '\nIf you think your configuration is valid and should keep working, please open a bug report.',
+    )}\n`,
+  );
+};