Gatsby

Install HumanBehavior in Gatsby with gatsby-browser onClientEntry and GATSBY public env vars.

Gatsby has dedicated browser, SSR, and Node APIs. HumanBehavior belongs in gatsby-browser.*, specifically onClientEntry, so tracking starts only in the browser bundle.

Wizard detection

The wizard detects Gatsby when it sees:

Signal	Details
`gatsby` dependency	Version read from `package.json`
`gatsby-config.js` / `.ts` / `.mjs`	Config-file fallback

Gatsby detection runs before generic React. Do not use the Vite React guide for Gatsby projects.

Package

pnpm add humanbehavior-js

Environment variables

GATSBY_HUMANBEHAVIOR_API_KEY=your-api-key
GATSBY_HUMANBEHAVIOR_INGESTION_URL=https://ingest.humanbehavior.co

Gatsby exposes GATSBY_ prefixed variables to browser code.

Init in `gatsby-browser.tsx`

import { HumanBehaviorTracker } from "humanbehavior-js";
import type { GatsbyBrowser } from "gatsby";

export const onClientEntry: GatsbyBrowser["onClientEntry"] = () => {
  const apiKey = process.env.GATSBY_HUMANBEHAVIOR_API_KEY;
  if (!apiKey) return;

  HumanBehaviorTracker.init(apiKey, {
    ingestionUrl: process.env.GATSBY_HUMANBEHAVIOR_INGESTION_URL,
  });
};

For JavaScript projects, use gatsby-browser.js with the same body.

Do not initialize in server files

Gatsby file	Status
`gatsby-browser.js` / `.tsx`	Recommended
`gatsby-ssr.js`	Do not initialize
`gatsby-node.js`	Do not initialize
React page component `useEffect`	Works but can repeat across pages; prefer browser API

onClientEntry fires once when the client bundle loads.

Options example

export const onClientEntry: GatsbyBrowser["onClientEntry"] = () => {
  const apiKey = process.env.GATSBY_HUMANBEHAVIOR_API_KEY;
  if (!apiKey) return;

  HumanBehaviorTracker.init(apiKey, {
    ingestionUrl: process.env.GATSBY_HUMANBEHAVIOR_INGESTION_URL,
    release: process.env.GATSBY_APP_VERSION,
    environment: process.env.GATSBY_DEPLOY_ENV,
    redactionStrategy: { mode: "visibility-first" },
  });
};

Only expose metadata that is safe for browser code.

Gatsby route changes

Gatsby's client router uses browser history. The SDK automatically records navigation events in normal Gatsby apps.

If you need a Gatsby-specific hook anyway, keep the tracker instance and use onRouteUpdate:

let tracker: HumanBehaviorTracker | null = null;

export const onClientEntry: GatsbyBrowser["onClientEntry"] = () => {
  const apiKey = process.env.GATSBY_HUMANBEHAVIOR_API_KEY;
  if (!apiKey) return;
  tracker = HumanBehaviorTracker.init(apiKey);
};

export const onRouteUpdate: GatsbyBrowser["onRouteUpdate"] = () => {
  void tracker?.trackPageView();
};

Most Gatsby sites do not need the manual onRouteUpdate call.

Common pitfalls

Pitfall	Symptom	Fix
Env var lacks `GATSBY_`	`undefined` in browser bundle	Rename and rebuild
Init in `gatsby-ssr`	Server/DOM errors	Move to `gatsby-browser`
Adding init to every page	Duplicate setup attempts	Use `onClientEntry` once
Deploy env changed without rebuild	Old key remains in bundle	Rebuild/redeploy Gatsby
Source maps uploaded without matching `release`	Minified stacks remain unreadable	Set `release` and upload source maps

Wizard config summary

Wizard field	Value
Integration	`gatsby`
Env vars	`GATSBY_HUMANBEHAVIOR_API_KEY`, `GATSBY_HUMANBEHAVIOR_INGESTION_URL`
Detection	`gatsby` dependency or `gatsby-config.*`
Reference entry	`gatsby-browser.tsx`

Error and release docs

Gatsby production builds often minify aggressively. For useful Issues:

Set release in init.
Upload source maps for that release.
Stamp environment if you have staging/production.

See Source maps.

Verify

Restart/rebuild after env changes.
Open the Gatsby site in a browser.
Confirm ingestion requests return 2xx.
Navigate between pages.
Open Replays.

Full checklist: Verify data is flowing.

Gatsby

On this page