@nuxtjs/plausible
TypeScript icon, indicating that this package has built-in type declarations

0.2.4 • Public • Published

Nuxt Plausible module

Nuxt Plausible

npm version

Nuxt 3 module to integrate the Plausible tracker.

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 @nuxtjs/plausible

# npm
npm i -D @nuxtjs/plausible

Basic Usage

Add @nuxtjs/plausible to the modules section of your Nuxt configuration:

// `nuxt.config.ts`
export default defineNuxtConfig({
  modules: ['@nuxtjs/plausible'],
})

Done! Plausible will now run in your application's client.

[!TIP] By default, @nuxtjs/plausible will use window.location.hostname for the Plausible domain configuration key, which will suit most users.

Configuration

All supported module options can be configured using the plausible key in your Nuxt configuration:

export default defineNuxtConfig({
  modules: ['@nuxtjs/plausible'],

  plausible: {
    domain: 'example.com',
  },
})

Runtime Config

Alternatively, leveraging automatically replaced public runtime config values by matching environment variables at runtime, set your desired option in your project's .env file:

# Sets the `plausible.domain` option to `example.com`
NUXT_PUBLIC_PLAUSIBLE_DOMAIN=example.com

With this setup, you can omit the plausible key in your Nuxt configuration.

Module Options

Option Type Default Description
hashMode boolean false Whether page views shall be tracked when the URL hash changes. Enable this if your Nuxt app has the hashMode router option enabled.
trackLocalhost boolean false Whether events shall be tracked when running the site locally.
domain string 'window.location.hostname' The domain to bind tracking event to.
apiHost string https://plausible.io The API host where the events will be sent to.
autoPageviews boolean true Track the current page and all further pages automatically. Disable this if you want to manually manage pageview tracking.
autoOutboundTracking boolean false Track all outbound link clicks automatically. If enabled, a MutationObserver automagically detects link nodes throughout the application and binds click events to them.

Composables

As with other composables in the Nuxt 3 ecosystem, they are auto-imported and can be used in your application's components.

ℹ️ Since the Plausible instance is available in the client only, executing the composables on the server will have no effect.

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

  1. Clone this repository
  2. Enable Corepack using corepack enable
  3. Install dependencies using pnpm install
  4. Run pnpm run dev:prepare
  5. Start development server using pnpm run dev

Similar Packages

License

MIT License © 2022-2023 Johann Schopplich

Package Sidebar

Install

npm i @nuxtjs/plausible

Weekly Downloads

3,484

Version

0.2.4

License

MIT

Unpacked Size

15.9 kB

Total Files

16

Last publish

Collaborators

  • antfu
  • danielroe
  • clarkdo
  • pi0
  • atinux
  • alexchopin
  • johannschopplich