pixelplicity / gatsby-plugin-plausible

Gatsby plugin to add Plausible analytics to your site.

gatsby-plugin-plausible

A Gatsby plugin for adding Plausible analytics to your Gatsby site.

The plugin includes the Plausible tracking script. It supports using a custom domain and excluding specific paths from recording page views.

---

• Install
  • Manual
  • Gatsby Recipe
• How to use
  • Options
  • Pageview events
  • Triggering custom events
• Changelog
• License

Install

Manual

1. Install gatsby-plugin-plausible

   npm install --save gatsby-plugin-plausible

2. Add plugin to gatsby-config.js

   // In your gatsby-config.js
   module.exports = {
     plugins: [
       // The only required option is the domain
       {
         resolve: `gatsby-plugin-plausible`,
         options: {
           domain: `aquil.io`,
         },
       },
     ],
   };

Gatsby Recipe

This will install gatsby-plugin-plausible and add a sample configuration.

1. Upgrade gatsby-cli and gatsby to the latest version:

   npm install -g gatsby-cli@latest npm install gatsby@latest

2. Run the recipe gatsby recipes https://raw.githubusercontent.com/Aquilio/gatsby-plugin-plausible/master/gatsby-recipe-plausible.mdx

3. Update gatsby-config.js options.

To read more about recipes check out the announcement.

How to use

NOTE: By default, this plugin only generates output when run in production mode. To test your tracking code, run gatsby build && gatsby serve.

Options

Option	Explanation
domain	The domain configured in Plausible (required)
customDomain	Custom domain (if configured in Plausible's dashboard)
excludePaths	Array of pathnames where page views will not be sent

Pageview events

Pageviews are sent automatically when a user changes routes, including the initial load of your site.

Triggering custom events

To track goals and conversions you have to trigger custom events first.

window.plausible('Signup', {
  callback: () => console.info('Sent Signup event'),
});

The event name can be anything. The second argument is an object with options. The only supported option is callback that is called once the event has been sent.

NOTE: Custom events will not show up right away. You have to configure a goal in your Plausible dashboard.

Changelog

See CHANGELOG.md.

License

MIT © Pixelplicity

gatsby-plugin-plausible's Issues

Option to use outbound link version

Hello and thank you for this wonderful plug-in 👍

I was able to get up and running incredibly quickly. I was just curious to ask if there were plans to offer an option to use the outbound link click tracking version of Plausible through this plugin?

If there already is and I’m missing it, I apologize!

Customizing for proxying

Hi there,

Plausible allow to proxy the script and the API call.
See: https://plausible.io/docs/proxy/guides/netlify

It should be nice to be able to configure the src and the data-api attribute:

<script defer data-domain="yourdomain.com" data-api="/my-api-path" src="/my-script-path.js"></script>

Selfhosted support

Hi there

Would it be possible for a tweak to add support for self hosted plausible instances please?

Perhaps another option selfhostedDomain: plausible.mydomain.com or selfhosted: true and use the customDomain still...?

allowing the creation of a url as follows;

<script async defer data-domain="mydomain.com" src="https://plausible.mydomain.com/js/plausible.js"></script>

High Severity ReDoS Vulnerability in minimatch Dependency of gatsby-plugin-plausible

Description:
gatsby-plugin-plausible depends on outdated versions of minimatch (< 3.0.5), which is known to have a high severity ReDoS vulnerability as per GHSA-f8q6-p94x-37v3. Currently, there's no fix available.

Affected Files:

node_modules/gatsby-plugin-plausible/node_modules/minimatch

Steps to Reproduce:

Install gatsby-plugin-plausible.
Check the installed version of minimatch in the node_modules directory.

Expected Result:
minimatch version should be 3.0.5 or later to avoid the ReDoS vulnerability.

Actual Result:
minimatch version is earlier than 3.0.5, exposing the plugin to the ReDoS vulnerability.

Suggested Fix:
Update the minimatch dependency to version 3.0.5 or later.

async AND defer potentially leading to render blocking

gatsby-plugin-plausible/src/gatsby-ssr.js

Line 37 in c055825

async: true,

This is potentially an issue in performance. Newer browsers only respect the async attribute if both, async and defer, are specified. This is could lead to render-blocking, because async only loads the scripts asynchronously but executes it right after the loading, which would block the rendering if it is still running.

This is why webpagetest also detects it as potentially_blocking (indicating it is using async and not defer):

I suggest only using defer, because it is supported by almost 99% of browsers:
https://caniuse.com/?search=defer

Incorrect snippet URL with latest self-hosted version

Thank you for this plugin! Unfortunately it's not working with self-hosted instances because it points to the wrong URL for the script. When using the latest version of the self-hosted Plausible, the script to be loaded in the snippet is hosted at:

https://custom.example.com/js/plausible.js

But when we configure the plugin to use the customDomain of custom.example.com, the snippet src becomes:

https://custom.example.com/js/index.js

And so it doesn't work...

Examples for "Triggering custom events"

Hi,

first of all thanks for this plugin!

Being rather new to JavaScript and React I have a hard time to wrap my head around the documentation for custom events.

I tried to get this to work for a few hours now and I think I understand why all my attempts fail (I think I always tried to evaluate it during the server side rendering of gatsby/react) but I still can't really figure out the right way to solve it. As far as I understand this code has to be evaluated on the client side when the page actually loads or the event is executed.

For example, I would like to include

window.plausible('404', {
  callback: () => console.info('custom 404 event logged'),
});

in my 404 error page and then use https://docs.plausible.io/404-error-pages-tracking/ to track those errors. What would be the right way to achieve this in gatsby? Do I need to do this in componentDidMount somehow?

I think the documentation would benefit from an example how to run such custom event at page load and on button press.
Any chance you could help me out here with a short explanation? I am happy to provide a pull request to extend the documentation afterwards :)

Thanks in advance
Max