next-plausible

To enable Plausible analytics, wrap your application (or specific pages) with the <PlausibleProvider /> component. You must provide the src prop with your site-specific script URL from the Plausible dashboard (e.g., https://plausible.io/js/pa-XXXXX.js).

Usage in Pages Router (_app.js): Wrap the top-level component to enable analytics globally.

Usage in App Router (layout.js): Wrap the children inside the root layout.

Single Page Usage: Wrap only the specific page component where analytics are desired.

// pages/_app.js
import PlausibleProvider from 'next-plausible'

export default function MyApp({ Component, pageProps }) {
  return (
    <PlausibleProvider src="https://plausible.io/js/pa-XXXXX.js">
      <Component {...pageProps} />
    </PlausibleProvider>
  )
}

When proxying, tracking requests are made to the same domain, meaning cookies are forwarded. If this is an issue, you can use Next.js middleware to strip cookies from requests targeting the proxy API endpoint.

Example Middleware Implementation:

import { NextResponse } from 'next/server'

export function middleware(request) {
  const requestHeaders = new Headers(request.headers)
  requestHeaders.set('cookie', '')
  return NextResponse.next({
    request: {
      headers: requestHeaders,
    },
  })
}

export const config = {
  matcher: '/proxy/api/event',
}

Use the usePlausible hook to access the plausible function for sending custom events and goals.

Basic Usage: Call plausible('eventName') to trigger an event.

With Properties: Pass an object with a props key to include metadata: plausible('eventName', { props: { key: 'value' } }).

TypeScript Support: You can provide a type definition to usePlausible<T>() to ensure only valid events and properties are sent.

import { usePlausible } from 'next-plausible'

type MyEvents = {
  event1: { prop1: string }
  event2: { prop3: string }
  event3: never
}

export default function PlausibleButton() {
  const plausible = usePlausible<MyEvents>()

  return (
    <button
      onClick={() =>
        plausible('event1', { props: { prop1: 'hello' } })
      }
    >
      Send Event
    </button>
  )
}

The init.customProperties option can be a static object or a function. If you use a function, it receives the eventName as an argument.

Important: The function must be self-contained. Because it is serialized into an inline script, it cannot reference variables defined outside its scope.

<PlausibleProvider
  src="https://plausible.io/js/pa-XXXXX.js"
  init={{
    customProperties: (eventName) => ({
      author: 'Alice',
    }),
  }}
/>

The init prop on <PlausibleProvider /> accepts an object of options passed directly to plausible.init(). Available options include:

In v4, all feature configuration is passed through the init object. This object is passed to plausible.init() at runtime.

<PlausibleProvider
  src="https://plausible.io/js/pa-XXXXX.js"
  init={{
    captureOnLocalhost: true,
    autoCapturePageviews: false,
    hashBasedRouting: true,
    fileDownloads: { fileExtensions: ['pdf', 'zip'] },
  }}
/>

The <PlausibleProvider /> component accepts the following props:

The PlausibleProvider component is the default export of the next-plausible package. It is used to wrap your application (typically in _app.tsx or layout.tsx) to provide the analytics context and manage the Plausible script injection.

import PlausibleProvider from 'next-plausible';

The withPlausibleProxy function is a named export used to proxy the Plausible analytics script through your own domain. This is useful for bypassing ad-blockers and improving privacy compliance.

import { withPlausibleProxy } from 'next-plausible';