gatsby-plugin-goatcounter
    TypeScript icon, indicating that this package has built-in type declarations

    0.4.0 • Public • Published

    Gatsby meets GoatCounter

    gatsby-plugin-goatcounter

    Adds GDPR compliant GoatCounter Statistics to your GatsbyJS website.

    Install

    yarn add -D gatsby-plugin-goatcounter
    # or 
    npm i -D gatsby-plugin-goatcounter

    It has peerDependencies on react & gatsby which are required by Gatsby anyways 😉

    How to use

    // In your gatsby-config.js
    module.exports = {
      plugins: [
        {
          resolve: `gatsby-plugin-goatcounter`,
          options: {
            // Either `code` or `selfHostUrl` is required.
            // REQUIRED IF USING HOSTED GOATCOUNTER! https://[my_code].goatcounter.com
            code: 'YOUR_GOATCOUNTER_PAGE_CODE',
     
            // REQUIRED IF USING SELFHOSTED GOATCOUNTER!
            selfHostUrl: `https://example.com`,
     
            // ALL following settings are OPTIONAL
     
            // Avoids sending pageview hits from custom paths
            exclude: [],
     
            // Delays sending pageview hits on route update (in milliseconds)
            pageTransitionDelay: 0,
     
            // Defines where to place the tracking script
            // boolean `true` in the head and `false` in the body
            head: false,
     
            // Set to true to include a gif to count non-JS users
            pixel: false,
     
            // Allow requests from local addresses (localhost, 192.168.0.0, etc.)
            // for testing the integration locally.
            // TIP: set up a `Additional Site` in your GoatCounter settings
            // and use its code conditionally when you `allowLocal`, example below
            allowLocal: false,
     
            // Override the default localStorage key more below
            localStorageKey: 'skipgc',
     
            // Set to boolean true to enable referrer set via URL parameters
            // Like example.com?ref=referrer.com or example.com?utm_source=referrer.com
            // Accepts a function to override the default referrer extraction
            // NOTE: No Babel! The function will be passes as is to your websites <head> section
            // So make sure the function works as intended in all browsers you want to support
            referrer: false,
     
            // Setting it to boolean true will clean the URL from
            // `?ref` & `?utm_` parameters before sending it to GoatCounter
            // It uses `window.history.replaceState` to clean the URL in the
            // browser address bar as well.
            // This is to prevent ref tracking ending up in your users bookmarks.
            // All parameters other than `ref` and all `utm_` will stay intact
            urlCleanup: false,
          },
        },
      ],
    }

    NOTE: The referrer and urlCleanup functions will only add to your page size if you explicitly enable them. This plugin uses minimatch for the exclude option, which will only be used at build time, so minimatch won't be added to your website.

    Tip: Additional Site to not spam your main analytics for testing purposes

    // In your gatsby-config.js
    // just an example, you can have your own logic how you decide what's production and what not.
    const isProduction = process.env.NODE_ENV === 'production'
    module.exports = {
      plugins: [
        {
          resolve:`gatsby-plugin-goatcounter`,
          options: {
            code: isProduction ? 'YOUR_GOATCOUNTER_PAGE_CODE' : 'GOATCOUNTER_DEV_CODE',
            allowLocal: !isProduction,
          },
        },
      ],
    }

    This way you can test locally without spamming your statistics 😉

    manual counting

    You can useGoatCounter to manually track events

    import { useGoatCounter } from 'gatsby-plugin-goatcounter'
     
    const Layout = (props) => {
      const count = useGoatCounter()
     
      count({
        path: 'event-name',
        event: true,
      })
     
      count({
        path: 'event-name',
        title: 'Event Name',
        referrer: 'example.com',
        event: true,
      })
     
      return <h1>GaiAma.org is saving as much rainforest as possible</h1>
    }

    useGoatCounter returns a noop function, meaning a no-operation function which does nothing, until GoatCounter.js has loaded. The component will then re-render and send the event.

    Skip own views

    gatsby-plugin-goatcounter skips views if the localStorageKey by default skipgc has been set in localStorage. You have to visit you-url.com/#skipgc (or you defined localStorageKey) once or set it manually to 't'. Why 't'? I basically copied the example from GoatCounter settings. Naming things is hard 😅

    Changelog

    v.0.4.0

    • Add support for self-hosted GoatCounter instances
    • Fix missing commas and wrong semicolons in readme examples

    v.0.3.1

    • Add missing note about referrer option

    v.0.3.0

    • Add support for ?ref=referrer.com & ?utm_source=referrer.com
    • Add boolean urlCleanup option

    v.0.2.0

    • BREAKING CHANGE: drops goatcount in favor of useGoatCounter hook
    • not tagged as beta yet it's still not widely tested
    • I'd appreciate bug reports & feature requests. 🙏

    I plan to add a component to track outbound links like gatsby-plugin-google-analytics

    For now count.js (GoatCounter's minimalistic js file) is loaded once from the official CDN. Eventually it'll be bundled and inlined, want to talk to GoatCounter for this first tho.

    Questions? Anything unclear?

    Feel free to open an issue or reach out via Twitter @CanRau.

    Who uses gatsby-plugin-goatcounter?

    License

    MIT © CanRau

    Install

    npm i gatsby-plugin-goatcounter

    DownloadsWeekly Downloads

    115

    Version

    0.4.0

    License

    MIT

    Unpacked Size

    21.3 kB

    Total Files

    8

    Last publish

    Collaborators

    • canrau