or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

index.mddocs/

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