Skip to content

Use gatsby-plugin-fathom to add Fathom Analytics tracking to your Gatsby site.

Notifications You must be signed in to change notification settings

queen-raae/gatsby-plugin-fathom

Repository files navigation

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.

Buy Me a Coffee at ko-fi.com

Stay updated

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


Social Media Image

About

Use gatsby-plugin-fathom to add Fathom Analytics tracking to your Gatsby site.

Topics

Resources

Stars

Watchers

Forks

Packages

No packages published