How to Add Orbit Analytics to a Gatsby Site

Gatsby pre-builds every page at build time, so tracking has to be baked into the generated HTML rather than added at runtime. The onRenderBody API in gatsby-ssr.js is the standard way to do that for every page in the build.

Setup steps

  1. Open gatsby-ssr.jsAt the root of your project (create it if it doesn't already exist) — this file controls the server-rendered HTML output, including the <head>.
  2. Implement onRenderBodyExport the onRenderBody API and use the setHeadComponents function it receives to inject arbitrary elements into the page head.
  3. Add the Orbit script elementCall setHeadComponents with a <script> element (defer, src, and data-website-id set as props) so it ends up in every statically generated page.
  4. Or use gatsby-plugin-load-scriptIf you'd rather not edit gatsby-ssr.js directly, install a script-loading plugin like gatsby-plugin-load-script and configure it with Orbit's script tag instead.
  5. Rebuild and deployGatsby needs a full rebuild (gatsby build) to bake the script into the generated HTML — redeploy rather than just restarting the dev server.

Frequently asked questions

Does onRenderBody run for every page, including ones created via createPages?

Yes — onRenderBody runs once per page in the build, whether the page comes from a static file in src/pages or was created programmatically via the createPages API, so the script ends up in every page.

Does this work on Gatsby Cloud or any other static host?

Yes — since the script is baked into the static HTML output at build time, it works the same regardless of where the built files are hosted.

Should this go in gatsby-browser.js instead?

No — gatsby-browser.js controls client-side behavior after hydration, but the <head> content itself needs to be present in the initial HTML, which is what onRenderBody in gatsby-ssr.js controls.

Does Gatsby's image pipeline conflict with the script?

No — Orbit's script tag is unrelated to Gatsby's image and asset processing; it's a small external script loaded independently of that pipeline.

See it on your own site

Free for 1 website, no card required.