README.md

Nuxt Plausible

Native integration of Plausible Analytics for Nuxt.

Features

• 🌻 No configuration necessary
• 📯 Track events and page views manually with composables
• 🔀 Optional API proxy to avoid ad-blockers
• 📂 .env file support
• 🧺 Sensible default options
• 🦾 SSR-ready

Setup

npx nuxi@latest 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 API feature that allows you to route Plausible events through your Nitro server instead of sending them directly to Plausible's servers. This is useful if you want to prevent ad blockers from blocking requests to Plausible's domain. When proxy is enabled, the tracker will automatically route requests through the current origin.

To enable the proxy API, 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 default proxy endpoint is /api/__plausible_event__, but you can customize the path using the proxyBaseURL module option.

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 the hashMode router option instead of the default history mode.
domain	string	'window.location.hostname'	The domain to bind tracking event to.
ignoredHostnames	string[]	['localhost']	Hostnames to ignore when tracking events.
ignoreSubDomains	boolean	false	Ignore the hostname if it is a subdomain of ignoredHostnames.
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.
logIgnoredEvents	boolean	false	Log events to the console if they are ignored.
proxy	boolean	false	Whether to proxy the event endpoint through the current origin.
proxyBaseURL	string	'/api/__plausible_event__'	The base URL to proxy the event endpoint through.

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

Credits

• @Barbapapazes for his Plausible tracker rewrite

License

MIT License © 2022-PRESENT Johann Schopplich