Nuxt Plausible

Privacy-friendly web analytics for Nuxt, powered by Plausible.

• ✨  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
• 🦾 SSR-ready

Setup

npx nuxt module add plausible

The command installs @nuxtjs/plausible and adds it to the modules section of your Nuxt configuration. Plausible now runs in your application's client. The Plausible domain is window.location.hostname unless you set the domain option.

Configuration

Set the module options under the plausible key of your Nuxt configuration.

Ignore Hostnames

Your ignoredHostnames list replaces the default ['localhost'], so keep localhost in it:

export default defineNuxtConfig({
  plausible: {
    // Skip tracking on the staging domain as well as localhost
    ignoredHostnames: ['localhost', 'staging.example.com'],
  },
})

!TIP To track events on localhost, set ignoredHostnames to an empty array. This also starts counting automated browsers on every hostname, your production one included.

Set Options From Environment Variables

Set options in your project's .env file – Nuxt replaces public runtime config values with matching environment variables at runtime:

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

The array and object options, ignoredHostnames and fileDownloads, take JSON:

NUXT_PUBLIC_PLAUSIBLE_IGNORED_HOSTNAMES='["localhost","staging.example.com"]'

With this setup, you can omit the plausible key in your Nuxt configuration – except for proxy and proxyBaseEndpoint, which are read when the app is built.

Proxy Events Through Your Server

The proxy routes Plausible events through your Nitro server instead of sending them straight to Plausible's servers, which keeps ad blockers from blocking requests to Plausible's domain.

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

export default defineNuxtConfig({
  plausible: {
    proxy: true,
  },
})

The route is /_plausible/api/event. A build with enabled set to false 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.

Behind a reverse proxy or load balancer, make sure it sets the x-forwarded-for header – without it, Plausible receives the reverse proxy's address for every visitor.

The route answers 413 for a body over 8 KB. A Plausible event is a few hundred bytes, and the route takes no authentication.

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

Track Outbound Links, File Downloads and Form Submissions

The official Plausible tracker tracks outbound link clicks, file downloads and form submissions:

export default defineNuxtConfig({
  plausible: {
    autoOutboundTracking: true,
    fileDownloads: true,
    formSubmissions: true,
  },
})

File download tracking covers common file types (pdf, xlsx, docx, zip, etc.) unless you name extensions yourself:

export default defineNuxtConfig({
  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

The composables are auto-imported and do nothing on the server.

useTrackEvent

Track a custom event. Pass a goal's name as eventName to record that goal.

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: 'https://example.com/virtual-page' })

PlausibleEventOptions

Both composables take the same options:

💻 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