Docs
Integrations
Gatsby

Install Statsy on Gatsby

This page is all about how to get Statsy up and running on Gatsby. We've made the steps easy to follow. If you're ready to use Statsy with Gatsby, you're in the right place. Let's get started!

View example on Github

Basic setup

Install gatsby-plugin-statsy

The Statsy React package is available on npm. It is recommended to install it with your package manager of choice.

pnpm i gatsby-plugin-statsy

Add gatsby-plugin-statsy to your gatsby-config.js

The Statsy React package provides a component that you can add to your app. It will automatically track page views and send them to Statsy.

gatsby-config.js
module.exports = {
  plugins: [
    // The only required option is the siteId
    {
      resolve: `gatsby-plugin-statsy`,
      options: {
        siteId: `YOUR_SITE_ID`,
      },
    },
  ],
};

Track custom events

You can track custom events by using the track function.

import { track } from "gatsby-plugin-statsy";
 
export default function Page() {
  return (
    <div>
      <button onClick={() => track("button-clicked")}>Click me</button>
    </div>
  );
}

Read more about:

Custom EventsTracking Script Settings

Advanced setup

Plugin options

The <Analytics /> component accepts the following props:

Prop nameTypeDescriptionRequired
siteIdstringThe ID of your site. You can find it in the Site Settings.Yes
modestringThe mode plugin should run in. If set to development it won't track any events.No
trackingEndpointDomainstringThe domain to use for tracking. Defaults to statsy.observer.No
autoTrackPageviewsbooleanWhether to automatically track page views. Defaults to true.No
excludearrayAn array of pathnames you don't want to be tracked.No
removeQueryParamsarrayAn array of query parameters you don't want to be tracked.No

Custom tracking endpoint domain

By default, the Statsy React package sends tracking requests to statsy.observer. You can change this by using the trackingEndpointDomain prop.

gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-statsy`,
      options: {
        siteId: `YOUR_SITE_ID`,
        trackingEndpointDomain: "statsy.example.com",
      },
    },
  ],
};

Learn more about custom domains in the Tracking Script section.

Excluding pathnames from tracking

By default, the Statsy React package tracks all page views. You can exclude specific pathnames by using the exclude prop.

gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-statsy`,
      options: {
        siteId: `YOUR_SITE_ID`,
        exclude: ["/admin/**", "/preview/**"],
      },
    },
  ],
};

Excluding query parameters from tracking

By default, the Statsy React package tracks all query parameters. You can exclude specific query parameters by using the removeQueryParams prop.

gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-statsy`,
      options: {
        siteId: `YOUR_SITE_ID`,
        removeQueryParams: ["token", "secretKey"],
      },
    },
  ],
};

Setting the mode

By default, the mode is set to auto and Statsy will try to detect the environment. If you want to force a specific mode, you can use the mode prop.

gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-statsy`,
      options: {
        siteId: `YOUR_SITE_ID`,
        mode: "development", // or "production",
      },
    },
  ],
};
Next.jsNuxt.js