A rewrite of plausible-tracker with extensibility and future features in mind.
Important
This is not a drop-in replacement.
The original tracker from the Plausible team have not received updates for more than 2 years.
Since then, the script tracker have evolved but not the npm package. The file downlaods and revenue tracking are not supported, for example.
Also, some serious issues were opened and not addressed. The outbound tracking was breaking the target="_blank" attribute, for example.
First, install the package:
npm install @barbapapazes/plausible-trackerThen, use it in your code:
import { createPlausibleTracker } from '@barbapapazes/plausible-tracker'
const plausible = createPlausibleTracker()
plausible.trackPageview() // Track a page view
plausible.trackEvent('signup') // Track a custom eventNote
The trackPageview is a wrapper around trackEvent with the pageview event name.
First argument of trackPageview and second of trackEvent is an object accepting props, data and a callback that is triggered after the event is sent.
Props are similar to the ones provided by the official Plausible script.
Data allows you to override some values like the url, referrer and deviceWidth.
plausible.trackEvent('signup', { props: { variation: 'button A' }, callback: () => console.log('sended') }) // Track a custom event with a custom prop with a callbackThis core tracker is minimal and does not include any extensions. So you can easily compose it to avoid to ship code that you don't need.
The extensions are the features that are not included in the core tracker.
Note
Extensions will help to maintain the package up to date with the official script.
Current extensions:
import { createPlausibleTracker } from '@barbapapazes/plausible-tracker'
import { useAutoPageviews } from '@barbapapazes/plausible-tracker/extensions'
const plausible = createPlausibleTracker()
const { install, cleanup, setEventOptions } = useAutoPageviews(plausible)
install()
// At any time, you can stop the auto pageview tracking
cleanup()
// You can also set the page options
setEventOptions({ props: { variation: 'button A' } })
// Now, every page view will include the prop `variation: 'button A'`import { createPlausibleTracker } from '@barbapapazes/plausible-tracker'
import { useAutoOutboundTracking } from '@barbapapazes/plausible-tracker/extensions'
const plausible = createPlausibleTracker()
const { install, cleanup, setEventOptions } = useOutboundLinkTracking(plausible)
install()
// At any time, you can stop the outbound link tracking
cleanup()
// You can also set the page options
setEventOptions({ props: { variation: 'button A' } })import { createPlausibleTracker } from '@barbapapazes/plausible-tracker'
import { useAutoFileDownloadsTracking } from '@barbapapazes/plausible-tracker/extensions'
const plausible = createPlausibleTracker()
const { install, cleanup, setEventOptions } = useFileDownloadsTracking(plausible, { fileTypes: [] }) // You can pass the file types to track. For example: ['pdf', 'zip']
install()
// At any time, you can stop the file downloads tracking
cleanup()
// You can also set the page options
setEventOptions({ props: { variation: 'button A' } })Important
By default, the file downloads does not track any file type. You need to pass the file types to track.
The package exports the defaultFileTypes that is an array with the most common file types which are the same as the official script.
import { defaultFileTypes } from '@barbapapazes/plausible-tracker/extensions'
const { install, cleanup, setEventOptions } = useFileDownloadsTracking(plausible, { fileTypes: defaultFileTypes })This allows you to easily customize the file types to track:
import { defaultFileTypes } from '@barbapapazes/plausible-tracker/extensions'
const { install, cleanup, setEventOptions } = useFileDownloadsTracking(plausible, { fileTypes: [...defaultFileTypes, 'svg'] })Contributions are more than welcome. I'm not part of the Plausible team and I'm doing this in my free time. 💛
- Fork the repository
- Install the dependencies:
pnpm install - Build the project:
pnpm build - Use playground to test your changes:
cd playground && pnpm dev
Thank you for your help!
This package is not affiliated with Plausible Analytics but inspired by their work. plausible-tracker Plausible Analytics Tracker