Fathom Analytics Gatsby Plugin

Add Fathom Analytics to your Gatsby site with @raae/gatsby-plugin-fathom.

Instead of messing with html.js as Fathom suggests, use this plugin to add the Fathom tracking script the Gatsby way.

Gatsby Plugin Fathom exposes all the advanced tracking options as plugin options.

Fathom Analytics

Fathom is a simple, light-weight, privacy-first alternative to Google Analytics. So, stop scrolling through pages of reports and collecting gobs of personal data about your visitors, both of which you probably don’t need. Our website stats show up on a single, blazingly fast dashboard so you can make business decisions quickly.

From the Fathom website.

How to install

npm install @raae/gatsby-plugin-fathom

or

yarn add @raae/gatsby-plugin-fathom

How to use

Basic configuration

The only required option is site.

module.exports = {
  plugins: [
    {
      resolve: `@raae/gatsby-plugin-fathom`,
      options: {
        site: "<your fathom site id>",
      },
    },
  ],
}

Feel free to use my test site id "CNOZPPSE" and check the dashboard to see if your setup is correct.

Advanced configuration

Learn more below and in Fathom's advanced tracking options docs.

module.exports = {
  plugins: [
    {
      resolve: `@raae/gatsby-plugin-fathom`,
      options: {
        site: <your fathom site id>,
        honorDnt: <true or false>,
        canonical: <true or false>,
        excludedDomains: <a comma-separated (no space) list of excluded domains>,
        includedDomains: <a comma-separated (no space) list of included domains>,
        spa: <"auto", "history" or "hash">
        loadType: <"defer" or "async">
      },
    },
  ],
}

Client side tracking

import React from "react";
import { useFathom } from "@raae/gatsby-plugin-fathom";

const Example = () => {
  const { trackGoal, trackPageview } = useFathom();
  return (
    <main>
      <button onClick={() => trackGoal("YKZ06A57", 100)}>Track goal</button>
      <br />
      <br />
      <button
        onClick={() =>
          trackPageview({
            url: "https://yoursite.com/about",
            referrer: "https://referrer.com/yoursite-link",
          })
        }
      >
        Track pageview
      </button>
    </main>
  );
};

export default Example;

Available options

Check the Fathom advanced tracking options docs for more information on these.

Name	Type	Default	Description
site	String	no default	Your Fathom site id (required)
honorDnt	Boolean	false	Honor Do Not Track?
auto	Boolean	true	Automatically track page views?
canonical	Boolean	true	Use the canonical URL, instead of the current URL?
excludedDomains	Comma separated list of domains, no spaces.	no default	Excludes tracking for these domains
includedDomains	Comma separated list of domains, no spaces.	no default	Include tracking for these domains
spa	"auto", "history" or "hash"	"auto"	Tracking mode
loadType	"defer" or "async"	"defer"	Tracking mode

How to contribute

Questions, Feedback and Suggestions

If you have any questions, feedback or suggestions head on over to discussions.

Bugs

If you find a bug please open an issue and/or create a pull request to fix it.

Support

If you got some value out of this plugin consider buying me a coffee or two.

Stay updated

Stay updated on the development of this plugin by subscribing to updates from @raae.

---