nuxt-plausible
This module provides a minimal Plausible tracker integration with Nuxt.
Features
🌻 No configuration necessary📯 Track events and page views manually with composables📂 .env
file support🧺 Sensible default options🦾 SSR-ready
Setup
# pnpm
pnpm add -D nuxt-plausible
# npm
npm i -D nuxt-plausible
Basic Usage
Add nuxt-plausible
to your Nuxt config:
// `nuxt.config.ts`
export default defineNuxtConfig({
modules: ['nuxt-plausible'],
})
Done! Plausible will now run in your application's client.
ℹ️ By default,nuxt-plausible
will usewindow.location.hostname
for the Plausibledomain
configuration key, which will suit most users.
Configuration
All supported module options can be set by either the module options key plausible
, or the public runtime config key with the same name.
export default defineNuxtConfig({
modules: ['nuxt-plausible'],
// Configure using the module options
plausible: {
domain: 'example.com',
},
// **Or** the public runtime config instead
runtimeConfig: {
public: {
plausible: {
domain: 'example.com',
},
},
},
})
Alternatively, leveraging automatically replaced public runtime config values by matching .env
variables at runtime, set your desired option in your project's .env
file:
# Sets the `plausible` public runtime config value for the key `domain`
NUXT_PUBLIC_PLAUSIBLE_DOMAIN=example.com
Module Options
Option | Type | Description | Default |
---|---|---|---|
hashMode |
boolean |
Whether page views shall be tracked when the URL hash changes. Enable this if your Nuxt app has the hashMode router option enabled. |
false |
trackLocalhost |
boolean |
Whether events shall be tracked when running the site locally. | false |
domain |
string |
The domain to bind tracking event to. | window.location.hostname |
apiHost |
string |
The API host where the events will be sent to. | https://plausible.io |
autoPageviews |
boolean |
Track the current page and all further pages automatically. Disable this if you want to manually manage pageview tracking. | true |
autoOutboundTracking |
boolean |
Track all outbound link clicks automatically. If enabled, a MutationObserver automagically detects link nodes throughout the application and binds click events to them. |
false |
Composables
As with other composables in the Nuxt 3 ecosystem, the following ones are available without the need of importing them.
ℹ️ Since the Plausible instance is available in the client only, calling the tracking composables will have no effect. They will exit gracefully on the server.
useTrackEvent
Track a custom event. Track your defined goals by passing the goal's name as the argument eventName
.
Type Declarations
function useTrackEvent(
eventName: string,
options?: EventOptions,
eventData?: PlausibleOptions,
): void
Example
// Tracks the `signup` goal
useTrackEvent('signup')
// Tracks the `Download` goal passing a `method` property.
useTrackEvent('Download', { props: { method: 'HTTP' } })
useTrackPageview
Manually track a page view.
Pass optional event data to be sent with the eventData
argument. Defaults to the current page's data merged with the default options provided during the Plausible initialization.
Type Declarations
function useTrackPageview(
eventData?: PlausibleOptions,
options?: EventOptions,
): void
💻 Development
- Clone this repository
- Enable Corepack using
corepack enable
(usenpm i -g corepack
for Node.js < 16.10) - Install dependencies using
pnpm install
- Run
pnpm run dev:prepare
- Start development server using
pnpm run dev
Similar Packages
- vue-plausible, without first-class Nuxt 3 and composables.
Credits
- SVGBackgrounds.com for the OpenGraph image background pattern.
License
MIT License © 2022 Johann Schopplich