Nuxt Plausible

Native integration of Plausible Analytics for Nuxt.

• ✨  Release Notes

Features

• 🌻 No configuration necessary
• 📯 Track events and page views manually with composables
• 📊 Automatic tracking of outbound links, file downloads, and form submissions
• 🔀 Optional API proxy to avoid ad blockers
• 📂 .env file support
• 🧺 Sensible default options
• 🦾 SSR-ready

Setup

npx nuxt module add 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 should suit most use cases. If you need to customize the domain, you can do so in the module options.

Configuration

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

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

  plausible: {
    // Prevent tracking on localhost
    ignoredHostnames: ['localhost'],
  },
})

!TIP To allow tracking events on localhost, set the ignoredHostnames option to an empty array.

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.

Proxy Configuration

The module provides a proxy feature that routes Plausible events through your Nitro server instead of sending them directly to Plausible's servers. This is useful to prevent ad blockers from blocking requests to Plausible's domain.

To enable the proxy, set the proxy option to true:

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

  plausible: {
    proxy: true,
  },
})

!NOTE When enabled, all Plausible events will be sent to your server first, which then forwards them to Plausible's API. The route is /_plausible/api/event; customize the /_plausible part with the proxyBaseEndpoint module option. Setting enabled to false switches the route off along with the tracker, so a build with tracking disabled exposes no forwarder.

Because the proxy answers on your own origin, the browser attaches the cookies your site has set. Only the headers Plausible reads travel on: the user-agent, which it attributes the visitor and their device by, the content-type of the event, and an x-forwarded-for carrying the visitor's IP address, which Plausible resolves the country from. Your cookies stay on your server.

!IMPORTANT Up to v3 the proxy forwarded every header of the incoming request. If you counted on one beyond these three reaching Plausible, it no longer travels.

Enhanced Tracking

The module supports automatic tracking of outbound link clicks, file downloads, and form submissions – all powered by the official Plausible tracker.

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

  plausible: {
    autoOutboundTracking: true,
    fileDownloads: true,
    formSubmissions: true,
  },
})

By default, file download tracking covers common file types (pdf, xlsx, docx, zip, etc.). You can customize which file extensions are tracked:

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

  plausible: {
    fileDownloads: { fileExtensions: ['pdf', 'zip', 'csv'] },
  },
})

!NOTE These features require the corresponding goals to be configured in your Plausible dashboard. Outbound link clicks are tracked as Outbound Link: Click, file downloads as File Download, and form submissions as Form: Submission.

Module Options

Composables

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

!NOTE Since the Plausible instance is only available on the client, 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?: PlausibleEventOptions,
): void

Example

// Tracks the `signup` goal
useTrackEvent('signup')

// Tracks the `Download` goal passing a `method` property
useTrackEvent('Download', { props: { method: 'HTTP' } })

// Tracks the `Purchase` goal with revenue data
useTrackEvent('Purchase', { revenue: { amount: 15.99, currency: 'USD' } })

useTrackPageview

Manually track a page view.

Type Declarations

function useTrackPageview(
  options?: PlausibleEventOptions,
): void

Example

useTrackPageview()

// Track with a custom URL
useTrackPageview({ url: '/virtual-page' })

💻 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

License

MIT License © 2022-PRESENT Johann Schopplich