refactor(ganalytics, gtag): move options out of themeConfig (#5832)

* refactor(ganalytics, gtag): move options out of themeConfig * Forbid themeConfig options * Add PR link * Add key names to error message * Fix? * Doc updates Co-authored-by: Sébastien Lorber <[email protected]>
facebook · Nov 10, 2021 · ac88d97 · ac88d97
1 parent f5732e7
commit ac88d97
Show file tree

Hide file tree

Showing 14 changed files with 270 additions and 102 deletions.
diff --git a/packages/docusaurus-module-type-aliases/src/index.d.ts b/packages/docusaurus-module-type-aliases/src/index.d.ts
@@ -22,7 +22,7 @@ declare module '@generated/site-metadata' {
   import type {DocusaurusSiteMetadata} from '@docusaurus/types';
 
   const siteMetadata: DocusaurusSiteMetadata;
-  export default siteMetadata;
+  export = siteMetadata;
 }
 
 declare module '@generated/registry' {
@@ -48,13 +48,13 @@ declare module '@generated/routes' {
 
 declare module '@generated/routesChunkNames' {
   const routesChunkNames: Record<string, Record<string, string>>;
-  export default routesChunkNames;
+  export = routesChunkNames;
 }
 
 declare module '@generated/globalData' {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const globalData: Record<string, any>;
-  export default globalData;
+  export = globalData;
 }
 
 declare module '@generated/i18n' {
@@ -64,12 +64,12 @@ declare module '@generated/i18n' {
     currentLocale: string;
     localeConfigs: Record<string, {label: string; direction: string}>;
   };
-  export default i18n;
+  export = i18n;
 }
 
 declare module '@generated/codeTranslations' {
   const codeTranslations: Record<string, string>;
-  export default codeTranslations;
+  export = codeTranslations;
 }
 
 declare module '@theme-original/*';

diff --git a/packages/docusaurus-plugin-google-analytics/package.json b/packages/docusaurus-plugin-google-analytics/package.json
@@ -18,7 +18,8 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.9"
+    "@docusaurus/core": "2.0.0-beta.9",
+    "@docusaurus/utils-validation": "2.0.0-beta.9"
   },
   "devDependencies": {
     "@docusaurus/types": "2.0.0-beta.9"

diff --git a/packages/docusaurus-plugin-google-analytics/src/index.ts b/packages/docusaurus-plugin-google-analytics/src/index.ts
@@ -6,30 +6,23 @@
  */
 
 import path from 'path';
-import type {LoadContext, Plugin, HtmlTags} from '@docusaurus/types';
-import type {ThemeConfig} from '@docusaurus/plugin-google-analytics';
-
-export default function pluginGoogleAnalytics(context: LoadContext): Plugin {
-  const {
-    siteConfig: {themeConfig},
-  } = context;
-  const {googleAnalytics} = themeConfig as ThemeConfig;
-
-  if (!googleAnalytics) {
-    throw new Error(
-      `You need to specify "googleAnalytics" object in "themeConfig" with "trackingId" field in it to use docusaurus-plugin-google-analytics.`,
-    );
-  }
-
-  const {trackingID, anonymizeIP} = googleAnalytics;
-
-  if (!trackingID) {
-    throw new Error(
-      'You specified the "googleAnalytics" object in "themeConfig" but the "trackingID" field was missing. ' +
-        'Please ensure this is not a mistake.',
-    );
-  }
+import {Joi} from '@docusaurus/utils-validation';
+import type {
+  LoadContext,
+  Plugin,
+  HtmlTags,
+  OptionValidationContext,
+  ValidationResult,
+  ThemeConfig,
+  ThemeConfigValidationContext,
+} from '@docusaurus/types';
+import type {PluginOptions} from '@docusaurus/plugin-google-analytics';
 
+export default function pluginGoogleAnalytics(
+  context: LoadContext,
+  options: PluginOptions,
+): Plugin {
+  const {trackingID, anonymizeIP} = options;
   const isProd = process.env.NODE_ENV === 'production';
 
   return {
@@ -74,3 +67,26 @@ export default function pluginGoogleAnalytics(context: LoadContext): Plugin {
     },
   };
 }
+
+const pluginOptionsSchema = Joi.object<PluginOptions>({
+  trackingID: Joi.string().required(),
+  anonymizeIP: Joi.boolean().default(false),
+});
+
+export function validateOptions({
+  validate,
+  options,
+}: OptionValidationContext<PluginOptions>): ValidationResult<PluginOptions> {
+  return validate(pluginOptionsSchema, options);
+}
+
+export function validateThemeConfig({
+  themeConfig,
+}: ThemeConfigValidationContext<ThemeConfig>): ValidationResult<ThemeConfig> {
+  if (themeConfig.googleAnalytics) {
+    throw new Error(
+      'The "googleAnalytics" field in themeConfig should now be specified as option for plugin-google-analytics. More information at https://github.com/facebook/docusaurus/pull/5832.',
+    );
+  }
+  return themeConfig;
+}
diff --git a/packages/docusaurus-plugin-google-analytics/src/plugin-google-analytics.d.ts b/packages/docusaurus-plugin-google-analytics/src/plugin-google-analytics.d.ts
@@ -5,9 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-export interface ThemeConfig {
-  googleAnalytics?: {
-    trackingID: string;
-    anonymizeIP?: boolean;
-  };
-}
+export type PluginOptions = {
+  trackingID: string;
+  anonymizeIP: boolean;
+};
+
+export type Options = Partial<PluginOptions>;
diff --git a/packages/docusaurus-plugin-google-gtag/package.json b/packages/docusaurus-plugin-google-gtag/package.json
@@ -18,7 +18,8 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.9"
+    "@docusaurus/core": "2.0.0-beta.9",
+    "@docusaurus/utils-validation": "2.0.0-beta.9"
   },
   "devDependencies": {
     "@docusaurus/types": "2.0.0-beta.9"

diff --git a/packages/docusaurus-plugin-google-gtag/src/gtag.ts b/packages/docusaurus-plugin-google-gtag/src/gtag.ts
@@ -6,17 +6,16 @@
  */
 
 import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
-import siteConfig from '@generated/docusaurus.config';
-import type {ThemeConfig} from '@docusaurus/plugin-google-gtag';
+import globalData from '@generated/globalData';
+import type {PluginOptions} from '@docusaurus/plugin-google-gtag';
 
 export default (function () {
   if (!ExecutionEnvironment.canUseDOM) {
     return null;
   }
 
-  const {themeConfig} = siteConfig;
-  const {gtag} = themeConfig as ThemeConfig;
-  const {trackingID} = gtag!;
+  const {trackingID} = globalData['docusaurus-plugin-google-gtag']
+    .default as PluginOptions;
 
   return {
     onRouteUpdate({location}: {location: Location}) {

diff --git a/packages/docusaurus-plugin-google-gtag/src/index.ts b/packages/docusaurus-plugin-google-gtag/src/index.ts
@@ -6,35 +6,32 @@
  */
 
 import path from 'path';
-import type {LoadContext, Plugin, HtmlTags} from '@docusaurus/types';
-import type {ThemeConfig} from '@docusaurus/plugin-google-gtag';
-
-export default function pluginGoogleGtag(context: LoadContext): Plugin {
-  const {
-    siteConfig: {themeConfig},
-  } = context;
-  const {gtag} = themeConfig as ThemeConfig;
-
-  if (!gtag) {
-    throw new Error(
-      `You need to specify "gtag" object in "themeConfig" with "trackingId" field in it to use docusaurus-plugin-google-gtag.`,
-    );
-  }
-
-  const {anonymizeIP, trackingID} = gtag;
-
-  if (!trackingID) {
-    throw new Error(
-      'You specified the "gtag" object in "themeConfig" but the "trackingID" field was missing. ' +
-        'Please ensure this is not a mistake.',
-    );
-  }
+import {Joi} from '@docusaurus/utils-validation';
+import type {
+  LoadContext,
+  Plugin,
+  HtmlTags,
+  OptionValidationContext,
+  ValidationResult,
+  ThemeConfig,
+  ThemeConfigValidationContext,
+} from '@docusaurus/types';
+import type {PluginOptions} from '@docusaurus/plugin-google-gtag';
 
+export default function pluginGoogleGtag(
+  context: LoadContext,
+  options: PluginOptions,
+): Plugin {
+  const {anonymizeIP, trackingID} = options;
   const isProd = process.env.NODE_ENV === 'production';
 
   return {
     name: 'docusaurus-plugin-google-gtag',
 
+    async contentLoaded({actions}) {
+      actions.setGlobalData(options);
+    },
+
     getClientModules() {
       return isProd ? [path.resolve(__dirname, './gtag')] : [];
     },
@@ -83,3 +80,26 @@ export default function pluginGoogleGtag(context: LoadContext): Plugin {
     },
   };
 }
+
+const pluginOptionsSchema = Joi.object<PluginOptions>({
+  trackingID: Joi.string().required(),
+  anonymizeIP: Joi.boolean().default(false),
+});
+
+export function validateOptions({
+  validate,
+  options,
+}: OptionValidationContext<PluginOptions>): ValidationResult<PluginOptions> {
+  return validate(pluginOptionsSchema, options);
+}
+
+export function validateThemeConfig({
+  themeConfig,
+}: ThemeConfigValidationContext<ThemeConfig>): ValidationResult<ThemeConfig> {
+  if (themeConfig.gtag) {
+    throw new Error(
+      'The "gtag" field in themeConfig should now be specified as option for plugin-google-gtag. More information at https://github.com/facebook/docusaurus/pull/5832.',
+    );
+  }
+  return themeConfig;
+}
diff --git a/packages/docusaurus-plugin-google-gtag/src/plugin-google-gtag.d.ts b/packages/docusaurus-plugin-google-gtag/src/plugin-google-gtag.d.ts
@@ -5,9 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-export interface ThemeConfig {
-  gtag?: {
-    trackingID: string;
-    anonymizeIP?: boolean;
-  };
-}
+export type PluginOptions = {
+  trackingID: string;
+  anonymizeIP: boolean;
+};
+
+export type Options = Partial<PluginOptions>;
diff --git a/packages/docusaurus-preset-classic/src/index.ts b/packages/docusaurus-preset-classic/src/index.ts
@@ -29,9 +29,19 @@ export default function preset(
 ): Preset {
   const {siteConfig} = context;
   const {themeConfig} = siteConfig;
-  const {algolia, googleAnalytics, gtag} = themeConfig as Partial<ThemeConfig>;
+  const {algolia} = themeConfig as Partial<ThemeConfig>;
   const isProd = process.env.NODE_ENV === 'production';
-  const {debug, docs, blog, pages, sitemap, theme, ...rest} = opts;
+  const {
+    debug,
+    docs,
+    blog,
+    pages,
+    sitemap,
+    theme,
+    googleAnalytics,
+    gtag,
+    ...rest
+  } = opts;
 
   const themes: PluginConfig[] = [];
   themes.push(makePluginConfig('@docusaurus/theme-classic', theme));
@@ -50,13 +60,15 @@ export default function preset(
     plugins.push(makePluginConfig('@docusaurus/plugin-content-pages', pages));
   }
   if (isProd && googleAnalytics) {
-    plugins.push(require.resolve('@docusaurus/plugin-google-analytics'));
+    plugins.push(
+      makePluginConfig('@docusaurus/plugin-google-analytics', googleAnalytics),
+    );
   }
   if (debug || (debug === undefined && !isProd)) {
     plugins.push(require.resolve('@docusaurus/plugin-debug'));
   }
   if (isProd && gtag) {
-    plugins.push(require.resolve('@docusaurus/plugin-google-gtag'));
+    plugins.push(makePluginConfig('@docusaurus/plugin-google-gtag', gtag));
   }
   if (isProd && sitemap !== false) {
     plugins.push(makePluginConfig('@docusaurus/plugin-sitemap', sitemap));
@@ -65,7 +77,7 @@ export default function preset(
     throw new Error(
       `Unrecognized keys ${Object.keys(rest).join(
         ', ',
-      )} found in preset-classic configuration. The allowed keys are debug, docs, blog, pages, sitemap, theme. Check the documentation: https://docusaurus.io/docs/presets#docusauruspreset-classic for more information on how to configure individual plugins.`,
+      )} found in preset-classic configuration. The allowed keys are debug, docs, blog, pages, sitemap, theme, googleAnalytics, gtag. Check the documentation: https://docusaurus.io/docs/presets#docusauruspreset-classic for more information on how to configure individual plugins.`,
     );
   }
 

diff --git a/packages/docusaurus-preset-classic/src/preset-classic.d.ts b/packages/docusaurus-preset-classic/src/preset-classic.d.ts
@@ -12,13 +12,11 @@ export type Options = {
   pages?: false | import('@docusaurus/plugin-content-pages').Options;
   sitemap?: false | import('@docusaurus/plugin-sitemap').Options;
   theme?: import('@docusaurus/theme-classic').Options;
+  googleAnalytics?: import('@docusaurus/plugin-google-analytics').Options;
+  gtag?: import('@docusaurus/plugin-google-gtag').Options;
 };
 
 export type ThemeConfig = import('@docusaurus/types').ThemeConfig &
-  import('@docusaurus/theme-common').UserThemeConfig &
-  // Those plugins themeConfigs should rather be moved to preset/plugin options
-  // Plugin data can be made available to browser thank to the globalData api
-  import('@docusaurus/plugin-google-analytics').ThemeConfig &
-  import('@docusaurus/plugin-google-gtag').ThemeConfig & {
+  import('@docusaurus/theme-common').UserThemeConfig & {
     algolia?: unknown; // TODO type plugin
   };