Docusaurus Google Tag Manager Plugin

Google Tag Manager (gtm.js) plugin for Docusaurus that enables easy integration of Google Tag Manager functionality into Docusaurus-based documentation sites and static websites.

Package Information

• Package Name: @docusaurus/plugin-google-tag-manager
• Package Type: npm
• Language: TypeScript
• Installation: npm install @docusaurus/plugin-google-tag-manager

Core Imports

import pluginGoogleTagManager from "@docusaurus/plugin-google-tag-manager";

For CommonJS:

const pluginGoogleTagManager = require("@docusaurus/plugin-google-tag-manager");

Basic Usage

Configure the plugin in your docusaurus.config.js:

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-google-tag-manager',
      {
        containerId: 'GTM-XXXXXXX', // Your Google Tag Manager container ID
      },
    ],
  ],
};

The plugin automatically injects the necessary Google Tag Manager scripts in production builds only.

Capabilities

Plugin Factory Function

Creates a Google Tag Manager plugin instance for Docusaurus.

/**
 * Default export function that creates a Google Tag Manager plugin
 * @param context - Docusaurus load context
 * @param options - Plugin configuration options
 * @returns Plugin instance or null in non-production environments
 */
export default function pluginGoogleAnalytics(
  context: LoadContext,
  options: PluginOptions,
): Plugin | null;

Note: Despite the function name pluginGoogleAnalytics, this is actually the Google Tag Manager plugin implementation.

Options Validation

Validates plugin configuration options using Joi schema validation.

/**
 * Validates plugin options against the required schema
 * @param context - Option validation context containing validate function and options
 * @returns Validated and typed plugin options
 */
export function validateOptions({
  validate,
  options,
}: OptionValidationContext<Options, PluginOptions>): PluginOptions;

Types

Plugin Options

/**
 * Required plugin configuration options
 */
export interface PluginOptions {
  /** Google Tag Manager container ID (required) */
  containerId: string;
}

/**
 * User-facing options type where all fields are optional for input
 */
export type Options = Partial<PluginOptions>;

External Types

The plugin relies on several types from the Docusaurus ecosystem:

// From @docusaurus/types
interface LoadContext {
  // Docusaurus load context properties
}

interface Plugin {
  name: string;
  contentLoaded?(params: { actions: any }): void;
  injectHtmlTags?(): {
    headTags?: HtmlTag[];
    preBodyTags?: HtmlTag[];
  };
}

interface OptionValidationContext<TOptions, TPluginOptions> {
  validate: (schema: any, options: TOptions) => TPluginOptions;
  options: TOptions;
}

interface HtmlTag {
  tagName: string;
  attributes?: Record<string, string>;
  innerHTML?: string;
}

Plugin Behavior

Production-Only Operation

The plugin only operates in production environments (NODE_ENV === 'production'). In development, it returns null to avoid tracking during development.

HTML Injection

When active, the plugin automatically injects:

Head Tags:

• Preconnect link to https://www.googletagmanager.com for performance
• DataLayer initialization script
• Google Tag Manager initialization script with the configured container ID

Pre-body Tags:

• Noscript fallback iframe for users with JavaScript disabled

Global Data

The plugin sets the provided options as global data, making them accessible to other parts of the Docusaurus build system.

Validation Schema

The plugin uses Joi validation to ensure the containerId is provided as a required string field.

Error Handling

The plugin will fail validation if:

• containerId is not provided
• containerId is not a string type

Validation errors are handled by Docusaurus's plugin validation system and will prevent the build from completing.