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

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 uses window.location.hostname as the Plausible domain. Set the domain option to override it.

Configuration

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

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

Tip

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

Runtime Config

Alternatively, 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

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

Proxy Configuration

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,
  },
})

Note

The route is /_plausible/api/event. Setting enabled to false switches it 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.

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 one beyond these three reaching Plausible, it no longer travels.

Enhanced Tracking

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

Option	Type	Default	Description
enabled	boolean	true	Whether the tracker shall be enabled.
hashMode	boolean	false	Whether page views shall be tracked when the URL hash changes. Enable this if your Nuxt app uses hash-based routing.
domain	string	'window.location.hostname'	The domain to bind tracking events to.
ignoredHostnames	string[]	['localhost']	Hostnames to ignore when tracking events.
ignoreSubDomains	boolean	false	Also ignore subdomains of ignoredHostnames. Has no effect on localhost, so it does nothing until you add a hostname of your own.
apiHost	string	'https://plausible.io'	The API host to send events to.
autoPageviews	boolean	true	Track page views automatically. Disable this if you want to manually manage pageview tracking.
autoOutboundTracking	boolean	false	Track outbound link clicks automatically.
fileDownloads	boolean | { fileExtensions: string[] }	false	Track file downloads automatically. Pass an object to customize tracked file extensions.
formSubmissions	boolean	false	Track form submissions automatically.
logIgnoredEvents	boolean	false	Log ignored events to the console.
proxy	boolean	false	Route events through your own origin instead of the Plausible API host. See Proxy Configuration.
proxyBaseEndpoint	string	'/_plausible'	Base path the proxy answers on. The event route sits below it, at /_plausible/api/event.

Composables

The composables are auto-imported.

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. 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: '/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