CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-gatsby-plugin-fullstory

Plugin to add the tracking code for Fullstory.com

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Gatsby Plugin Fullstory

Gatsby Plugin Fullstory is a Gatsby plugin that integrates Fullstory analytics tracking into Gatsby websites. It provides a simple server-side rendering hook that injects the Fullstory tracking script into the HTML head during production builds.

Package Information

  • Package Name: gatsby-plugin-fullstory
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install gatsby-plugin-fullstory

Core Imports

Since this is a Gatsby plugin, you don't import it directly in your code. Instead, configure it in your gatsby-config.js:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-fullstory',
      options: {
        fs_org: 'YOUR_ORG_ID'
      }
    }
  ]
}

For Gatsby plugin development (if extending the plugin):

import { onRenderBody } from "gatsby-plugin-fullstory/gatsby-ssr";

Basic Usage

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-fullstory',
      options: {
        fs_org: 'ABCDEF' // Your Fullstory organization ID
      }
    }
  ]
}

The plugin automatically:

  • Injects Fullstory tracking script only in production builds (NODE_ENV === 'production')
  • Initializes the global FS namespace with the complete Fullstory client API
  • Sets up proper configuration variables for your organization

Capabilities

Server-Side Rendering Hook

The core functionality that injects Fullstory tracking code during Gatsby's server-side rendering process.

/**
 * Gatsby SSR API hook that injects Fullstory tracking script into HTML head
 * @param setHeadComponents - Gatsby function to add components to HTML head
 * @param pluginOptions - Configuration options for the plugin
 * @returns null (always returns null, effects are handled via setHeadComponents)
 */
export const onRenderBody = (
  { setHeadComponents },
  pluginOptions
) => null;

interface PluginOptions {
  /** Fullstory organization ID (required) */
  fs_org: string;
}

Fullstory Client API

When the tracking script is injected in production, it creates a global FS object with the complete Fullstory API:

// Global FS object available after script injection
interface FullstoryAPI {
  /** Identify a user with optional user variables and session variables */
  identify(userId: string, userVars?: object, sessionVars?: object): void;
  /** Set user variables for the current session */
  setUserVars(userVars: object, sessionVars?: object): void;
  /** Track a custom event with optional properties */
  event(eventName: string, properties?: object, sessionVars?: object): void;
  /** Anonymize the current user session */
  anonymize(): void;
  /** Stop session recording */
  shutdown(): void;
  /** Start session recording */
  restart(): void;
  /** Log a message for debugging */
  log(level: string, message: string): void;
  /** Set user consent status */
  consent(hasConsent?: boolean): void;
  /** Identify an account with account variables */
  identifyAccount(accountId: string, accountVars?: object): void;
  /** Clear the user cookie */
  clearUserCookie(): void;
  /** Set custom variables */
  setVars(name: string, properties: object): void;
}

// Available globally as window.FS
declare global {
  interface Window {
    FS: FullstoryAPI;
  }
}

Configuration Variables

The plugin sets these configuration variables on the window object:

interface FullstoryConfig {
  /** Debug mode setting (always false) */
  _fs_debug: boolean;
  /** Fullstory host domain */
  _fs_host: string;
  /** Fullstory script URL */
  _fs_script: string;
  /** Organization ID from plugin options */
  _fs_org: string;
  /** Global namespace for Fullstory API */
  _fs_namespace: string;
}

// Set on window object
declare global {
  interface Window {
    _fs_debug: boolean;
    _fs_host: string;
    _fs_script: string;
    _fs_org: string;
    _fs_namespace: string;
  }
}

Environment Behavior

  • Development: Plugin does nothing (onRenderBody returns null)
  • Production: Injects complete Fullstory tracking script and initializes client API

Error Handling

The plugin includes namespace conflict detection. If window.FS already exists, it logs a warning to the console and returns early to prevent conflicts.

Dependencies

  • Runtime: @babel/runtime: ^7.15.4
  • Peer Dependencies:
    • gatsby: ^4.0.0-next
    • react: ^16.9.0 || ^17.0.0 || ^18.0.0 || ^0.0.0
    • react-dom: ^16.9.0 || ^17.0.0 || ^18.0.0 || ^0.0.0
  • Node.js: >=14.15.0
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/gatsby-plugin-fullstory@4.25.x
Publish Source
CLI
Badge
tessl/npm-gatsby-plugin-fullstory badge