Beam for Gatsby

Install Beam on Gatsby

Replace YOUR_SITE_ID with your Beam site ID from the dashboard.

Add the script tag in gatsby-browser.js

// gatsby-browser.js (create if it doesn't exist)

export const onClientEntry = () => {
  const script = document.createElement('script')
  script.defer = true
  script.src = 'https://beam-privacy.com/js/beam.js'
  script.setAttribute('data-site-id', 'YOUR_SITE_ID')
  document.head.appendChild(script)
}

Gatsby's onClientEntry lifecycle fires once when the browser runtime loads. Injecting the script here ensures Beam initialises before the first route renders.

Track SPA route changes with onRouteUpdate

// gatsby-browser.js (add below onClientEntry)

export const onRouteUpdate = ({ location }) => {
  // Gatsby handles client-side navigation without full page reloads.
  // onRouteUpdate fires after every route transition.
  if (typeof window !== 'undefined' && window.beam) {
    window.beam.track('pageview', { path: location.pathname })
  }
}

Without this hook, Beam only captures the initial page load. onRouteUpdate fires on every Gatsby client-side navigation, keeping your Top Pages report accurate across all routes.

Verify your Gatsby integration

Use this checklist after publish so you know tracking is actually live in production.

✓ Run gatsby develop and open the site in a browser.
✓ Navigate between two pages using Gatsby Link components (not browser refresh).
✓ Open your Beam dashboard and confirm both paths appear in Top Pages within a minute.
✓ Check that no cookies or localStorage keys are set by the Beam script.

Why Beam works well for Gatsby

🍪

No cookie banner required

Beam is cookie-free by design — no consent UI to build, no GDPR overhead for your Gatsby site.

⚡

Sub-2KB, zero dependencies

Beam's tracking script adds no npm packages and is lighter than most Gatsby plugins.

🧭

Full SPA route tracking

The onRouteUpdate hook captures every Gatsby client-side navigation so your Top Pages report is complete.

🔒

Privacy by default

No PII, no fingerprinting, no ad-tech — just page-level metrics that work without a consent banner.