Simple integration for https://plausible.io analytics and https://nextjs.org.

See this commit for a real world example.

Important: If you're using a version of next lower than 11.1.0 please use next-plausible@2 to avoid type checking errors (see 4lejandrito#25).

To include the Plausible analytics script in your NextJS page just use the PlausibleProvider component:

import PlausibleProvider from 'next-plausible'

export default Home() {
  return (
    <PlausibleProvider domain="example.com">
      <h1>My Site</h1>
      ...
    </PlausibleProvider>
  )
}

If you want to include it globally for all your pages you can use the component in your custom _app.js file:

import PlausibleProvider from 'next-plausible'

export default function MyApp({ Component, pageProps }) {
  return (
    <PlausibleProvider domain="example.com">
      <Component {...pageProps} />
    </PlausibleProvider>
  )
}

To avoid being blocked by adblockers plausible recommends proxying the script. To do this you need to wrap your next.config.js with the withPlausibleProxy function:

const { withPlausibleProxy } = require('next-plausible')

module.exports = withPlausibleProxy()({
  // ...your next js config, if any
})

This will set up the necessary rewrites as described here and configure PlausibleProvider to use the local URLs so you can keep using it like this:

  <PlausibleProvider domain="example.com">
    ...
  </PlausibleProvider>
}

Note: This will only work if you serve your site using next start. Statically generated sites won't be able to rewrite the requests.

Optionally you can overwrite the proxied script subdirectory and name, as well as the custom domain for the original script:

const { withPlausibleProxy } = require('next-plausible')

module.exports = withPlausibleProxy({
  subdirectory: 'yoursubdirectory',
  scriptName: 'scriptName',
  customDomain: 'http://example.com',
})({
  // ...your next js config, if any
})

This will load the script from /js/yoursubdirectory/scriptName.js and fetch it from http://example.com/js/script.js.

Plausible supports custom events as described at https://plausible.io/docs/custom-event-goals. This package provides the usePlausible hook to safely access the plausible function like this:

import { usePlausible } from 'next-plausible'

export default function PlausibleButton() {
  const plausible = usePlausible()

  return (
    <>
      <button onClick={() => plausible('customEventName')}>Send</button>

      <button
        id="foo"
        onClick={() =>
          plausible('customEventName', {
            props: {
              buttonId: 'foo',
            },
          })
        }
      >
        Send with props
      </button>
    </>
  )
}

If you use Typescript you can type check your custom events like this:

import { usePlausible } from 'next-plausible'

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

const plausible = usePlausible<MyEvents>()

Only those events with the right props will be allowed to be sent using the plausible function.

• yarn build will generate the production scripts under the dist folder.