How to Add Plausible Analytics to Gatsby

Created: Nov 12, 2021 – Last Updated: Aug 22, 2023

Tags: Gatsby

You’re a fan of Plausible Analytics (opens in a new tab) and Gatsby (opens in a new tab)? Great! In this guide you’ll learn how to add Plausible Analytics to your Gatsby site, including support for TypeScript, 404 error page tracking, and custom events.

You should already have set up an account with Plausible and have your domain name at hand. It’s the name in the URL: https://plausible.io/<your-name>. Also want to learn how to use Deferred Static Generation with Plausible? You can also check out the post Using Deferred Static Generation with Analytics Tools afterwards.

#Setup

Edit the gatsby-ssr.jsx to add the tracking script. You can choose between a variety of script extensions (opens in a new tab) – you can edit it in the SCRIPT_URI variable. This also adds the snippet for 404 error page tracking (opens in a new tab).

gatsby-ssr.jsx

jsx

import * as React from "react"

const SITE_DOMAIN = `your-domain`
const PLAUSIBLE_DOMAIN = `plausible.io`
const SCRIPT_URI = `/js/script.js`

export const onRenderBody = ({ setHeadComponents }) => {
  if (process.env.NODE_ENV === `production`) {
    const scriptProps = {
      "data-domain": SITE_DOMAIN,
      src: `https://${PLAUSIBLE_DOMAIN}${SCRIPT_URI}`,
    }

    return setHeadComponents([
      <link
        key="plausible-preconnect"
        rel="preconnect"
        href={`https://${PLAUSIBLE_DOMAIN}`}
      />,
      <script key="plausible-script" defer {...scriptProps} />,
      // See: https://plausible.io/docs/custom-event-goals#1-trigger-custom-events-with-javascript-on-your-site
      <script
        key="plausible-custom-events"
        dangerouslySetInnerHTML={{
          __html: `
            window.plausible = window.plausible || function() { (window.plausible.q = window.plausible.q || []).push(arguments) };
          `,
        }}
      />,
    ])
  }
  return null
}

Edit the gatsby-browser.jsx to add pageview tracking:

gatsby-browser.jsx

jsx

export const onRouteUpdate = () => {
  if (
    process.env.NODE_ENV === `production` &&
    typeof window.plausible !== `undefined`
  ) {
    window.plausible(`pageview`)
  }
}

#TypeScript

In order to have IntelliSense on the custom events you’ll need to declare Plausible on the global window element. Create a declaration file or reuse your existing one with the following contents:

declare global {
  interface Window {
    plausible: (
      name: string,
      options?: { callback?: () => void; props?: { [key: string]: string } }
    ) => void
  }
}

#404 Error Page Tracking

Besides adding the custom event to the src/pages/404.jsx page you’ll also need to create a custom event goal in Plausible. See their documentation (opens in a new tab) to learn more.

Here’s an example of a 404 Page written in TypeScript:

src/pages/404.tsx

tsx

import * as React from "react"
import { PageProps } from "gatsby"

const NotFound: React.FC<PageProps> = () => {
  React.useEffect(() => {
    window.plausible(`404`, { props: { path: document.location.pathname } })
  }, [])

  return <main>404 - Not Found</main>
}

export default NotFound

Edit on GitHub - Share on Twitter / Mastodon

Want to learn more? Browse my Digital Garden