feat(plugin-google-tag-manager): add new google-tag-manager plugin + deprecate google-analytics plugin (#8470)

Co-authored-by: Goolsby, Lane <lanegoolsby@rocketmortgage.com>
Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
fix https://github.com/facebook/docusaurus/issues/7221

packages/docusaurus-plugin-google-tag-manager/.npmignore

@@ -0,0 +1,3 @@
+.tsbuildinfo*
+tsconfig*
+__tests__

packages/docusaurus-plugin-google-tag-manager/README.md

@@ -0,0 +1,7 @@
+# `@docusaurus/plugin-google-tag-manager`
+
+Google Tag Manager plugin for Docusaurus.
+
+## Usage
+
+See [plugin-google-tag-manager documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-google-tag-manager).

packages/docusaurus-plugin-google-tag-manager/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@docusaurus/plugin-google-tag-manager",
+  "version": "3.0.0-alpha.0",
+  "description": "Google Tag Manager (gtm.js) plugin for Docusaurus.",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "watch": "tsc --build --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/facebook/docusaurus.git",
+    "directory": "packages/docusaurus-plugin-google-tag-manager"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@docusaurus/core": "^3.0.0-alpha.0",
+    "@docusaurus/types": "^3.0.0-alpha.0",
+    "@docusaurus/utils-validation": "^3.0.0-alpha.0",
+    "tslib": "^2.4.0"
+  },
+  "peerDependencies": {
+    "react": "^16.8.4 || ^17.0.0",
+    "react-dom": "^16.8.4 || ^17.0.0"
+  },
+  "engines": {
+    "node": ">=16.14"
+  }
+}

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

@@ -0,0 +1,78 @@
+/**
+ * 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 {Joi} from '@docusaurus/utils-validation';
+import type {
+  LoadContext,
+  Plugin,
+  OptionValidationContext,
+} from '@docusaurus/types';
+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';
+
+  return {
+    name: 'docusaurus-plugin-google-tag-manager',
+
+    contentLoaded({actions}) {
+      actions.setGlobalData(options);
+    },
+
+    injectHtmlTags() {
+      if (!isProd) {
+        return {};
+      }
+      return {
+        preBodyTags: [
+          {
+            tagName: 'noscript',
+            innerHTML: `<iframe src="https://www.googletagmanager.com/ns.html?id=${containerId}" height="0" width="0" style="display:none;visibility:hidden"></iframe>`,
+          },
+        ],
+        headTags: [
+          {
+            tagName: 'link',
+            attributes: {
+              rel: 'preconnect',
+              href: 'https://www.googletagmanager.com',
+            },
+          },
+          {
+            tagName: 'script',
+            innerHTML: `window.dataLayer = window.dataLayer || [];`,
+          },
+          {
+            tagName: 'script',
+            innerHTML: `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
+new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
+j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
+'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
+})(window,document,'script','dataLayer','${containerId}');`,
+          },
+        ],
+      };
+    },
+  };
+}
+
+const pluginOptionsSchema = Joi.object<PluginOptions>({
+  containerId: Joi.string().required(),
+});
+
+export function validateOptions({
+  validate,
+  options,
+}: OptionValidationContext<Options, PluginOptions>): PluginOptions {
+  return validate(pluginOptionsSchema, options);
+}
+
+export type {PluginOptions, Options};

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

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+
+export type PluginOptions = {
+  containerId: string;
+};
+
+export type Options = Partial<PluginOptions>;

packages/docusaurus-plugin-google-tag-manager/src/types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+
+/// <reference types="@docusaurus/module-type-aliases" />

packages/docusaurus-plugin-google-tag-manager/tsconfig.client.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "composite": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./lib/.tsbuildinfo-client",
+    "module": "esnext",
+    "target": "esnext",
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "include": ["src/*.d.ts"],
+  "exclude": ["**/__tests__/**"]
+}

packages/docusaurus-plugin-google-tag-manager/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "references": [{"path": "./tsconfig.client.json"}],
+  "compilerOptions": {
+    "noEmit": false,
+    "incremental": true,
+    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "include": ["src"],
+  "exclude": ["**/__tests__/**"]
+}

packages/docusaurus-preset-classic/package.json

@@ -25,6 +25,7 @@
     "@docusaurus/plugin-debug": "^3.0.0-alpha.0",
     "@docusaurus/plugin-google-analytics": "^3.0.0-alpha.0",
     "@docusaurus/plugin-google-gtag": "^3.0.0-alpha.0",
+    "@docusaurus/plugin-google-tag-manager": "^3.0.0-alpha.0",
     "@docusaurus/plugin-sitemap": "^3.0.0-alpha.0",
     "@docusaurus/theme-classic": "^3.0.0-alpha.0",
     "@docusaurus/theme-common": "^3.0.0-alpha.0",

packages/docusaurus-preset-classic/src/index.ts

@@ -40,6 +40,7 @@ export default function preset(
     theme,
     googleAnalytics,
     gtag,
+    googleTagManager,
     ...rest
   } = opts;
 
@@ -80,6 +81,11 @@ export default function preset(
   if (gtag) {
     plugins.push(makePluginConfig('@docusaurus/plugin-google-gtag', gtag));
   }
+  if (googleTagManager) {
+    plugins.push(
+      makePluginConfig('@docusaurus/plugin-google-gtag', googleTagManager),
+    );
+  }
   if (isProd && sitemap !== false) {
     plugins.push(makePluginConfig('@docusaurus/plugin-sitemap', sitemap));
   }

packages/docusaurus-preset-classic/src/options.ts

@@ -11,6 +11,7 @@ import type {Options as PagesPluginOptions} from '@docusaurus/plugin-content-pag
 import type {Options as SitemapPluginOptions} from '@docusaurus/plugin-sitemap';
 import type {Options as GAPluginOptions} from '@docusaurus/plugin-google-analytics';
 import type {Options as GtagPluginOptions} from '@docusaurus/plugin-google-gtag';
+import type {Options as GTMPluginOptions} from '@docusaurus/plugin-google-tag-manager';
 import type {Options as ThemeOptions} from '@docusaurus/theme-classic';
 import type {ThemeConfig as BaseThemeConfig} from '@docusaurus/types';
 import type {UserThemeConfig as ClassicThemeConfig} from '@docusaurus/theme-common';
@@ -42,6 +43,7 @@ export type Options = {
    * is present.
    */
   gtag?: GtagPluginOptions;
+  googleTagManager?: GTMPluginOptions;
 };
 
 export type ThemeConfig = BaseThemeConfig &

website/docs/api/plugins/plugin-google-analytics.md

@@ -9,6 +9,16 @@ import APITable from '@site/src/components/APITable';
 
 The default [Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/) plugin. It is a JavaScript library for measuring how users interact with your website **in the production build**. If you are using Google Analytics 4 you might need to consider using [plugin-google-gtag](./plugin-google-gtag.md) instead.
 
+:::danger Deprecated
+
+This plugin is **deprecated**, and will become useless on July 1, 2023.
+
+Google is [moving away from Universal Analytics](https://blog.google/products/marketingplatform/analytics/prepare-for-future-with-google-analytics-4/).
+
+If you are still using this plugin with a `UA-*` tracking id, you should create a Google Analytics 4 account as soon as possible, and use [`@docusaurus/plugin-google-gtag`](./plugin-google-gtag.md) instead of this plugin. More details [here](https://github.com/facebook/docusaurus/issues/7221).
+
+:::
+
 :::caution production only
 
 This plugin is always inactive in development and **only active in production** to avoid polluting the analytics statistics.

website/docs/api/plugins/plugin-google-tag-manager.md

@@ -0,0 +1,71 @@
+---
+sidebar_position: 8
+slug: /api/plugins/@docusaurus/plugin-google-tag-manager
+---
+
+# 📦 plugin-google-tag-manager
+
+import APITable from '@site/src/components/APITable';
+
+A plugin for adding [Google Tag Manager (gtm.js)](https://developers.google.com/tag-platform/tag-manager) to a Docusaurus site. Use this plugin in conjunction with the standard [gtag plugin](./plugin-google-gtag.md) for in-depth analysis of how users are using your site.
+
+:::tip
+
+You can use [Google's Tag Assistant](https://tagassistant.google.com/) tool to check if tag manager is set up correctly!
+
+:::
+
+:::caution production only
+
+This plugin is always inactive in development and **only active in production** to avoid polluting the analytics statistics.
+
+:::
+
+## Installation {#installation}
+
+```bash npm2yarn
+npm install --save @docusaurus/plugin-google-tag-manager
+```
+
+:::tip
+
+If you use the preset `@docusaurus/preset-classic`, you don't need to install this plugin as a dependency.
+
+You can configure this plugin through the preset options.
+
+:::
+
+## Configuration {#configuration}
+
+Accepted fields:
+
+```mdx-code-block
+<APITable>
+```
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `containerId` | `string` | **Required** | Your Tag Manager container Id (usually starts with `GTM-`). |
+
+```mdx-code-block
+</APITable>
+```
+
+### Example configuration {#ex-config}
+
+You can configure this plugin through preset options or plugin options.
+
+:::tip
+
+Most Docusaurus users configure this plugin through the preset options.
+
+:::
+
+```js config-tabs
+// Preset Options: googleTagManager
+// Plugin Options: @docusaurus/plugin-google-tag-manager
+
+const config = {
+  containerId: 'GTM-12345',
+};
+```

website/docs/using-plugins.md

@@ -144,8 +144,9 @@ The classic preset is shipped by default to new Docusaurus websites created with
 - [`@docusaurus/plugin-content-blog`](./api/plugins/plugin-content-blog.md)
 - [`@docusaurus/plugin-content-pages`](./api/plugins/plugin-content-pages.md)
 - [`@docusaurus/plugin-debug`](./api/plugins/plugin-debug.md)
-- [`@docusaurus/plugin-google-analytics`](./api/plugins/plugin-google-analytics.md)
 - [`@docusaurus/plugin-google-gtag`](./api/plugins/plugin-google-gtag.md)
+- [`@docusaurus/plugin-google-tag-manager`](./api/plugins/plugin-google-tag-manager.md)
+- [`@docusaurus/plugin-google-analytics`](./api/plugins/plugin-google-analytics.md) (**deprecated**)
 - [`@docusaurus/plugin-sitemap`](./api/plugins/plugin-sitemap.md)
 
 The classic preset will relay each option entry to the respective plugin/theme.
@@ -172,7 +173,9 @@ module.exports = {
         sitemap: {},
         // Will be passed to @docusaurus/plugin-google-gtag (only enabled when explicitly specified)
         gtag: {},
-        // Will be passed to @docusaurus/plugin-google-analytics (only enabled when explicitly specified)
+        // Will be passed to @docusaurus/plugin-google-tag-manager (only enabled when explicitly specified)
+        googleTagManager: {},
+        // DEPRECATED: Will be passed to @docusaurus/plugin-google-analytics (only enabled when explicitly specified)
         googleAnalytics: {},
       },
     ],