next-plausible
Advanced tools
Simple integration for https://nextjs.org and https://plausible.io analytics.
Simple integration for https://nextjs.org and https://plausible.io analytics.
See it in action at https://next-plausible.vercel.app, and 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 https://github.com/4lejandrito/next-plausible/issues/25).
To enable Plausible analytics in your Next.js app you'll need to expose the Plausible context, <PlausibleProvider />, at the top level of your application inside _app.js:
// pages/_app.js
import PlausibleProvider from 'next-plausible'
export default function MyApp({ Component, pageProps }) {
return (
<PlausibleProvider domain="example.com">
<Component {...pageProps} />
</PlausibleProvider>
)
}
If you want to enable Plausible analytics only on a single page you can wrap the page in a PlausibleProvider component:
// pages/home.js
import PlausibleProvider from 'next-plausible'
export default Home() {
return (
<PlausibleProvider domain="example.com">
<h1>My Site</h1>
{/* ... */}
</PlausibleProvider>
)
}
If are using the app directory include PlausibleProvider inside the root layout:
// app/layout.js
import PlausibleProvider from 'next-plausible'
export default function RootLayout({ children }) {
return (
<html>
<head>
<PlausibleProvider domain="example.com" />
</head>
<body>{children}</body>
</html>
)
}
PlausibleProvider Props| Name | Description |
|---|---|
domain | The domain of the site you want to monitor. |
customDomain | Set this if you use a custom domain to serve the analytics script. Defaults to https://plausible.io. See https://plausible.io/docs/custom-domain for more details. |
trackOutboundLinks | Set this to true if you want to enable outbound link click tracking. |
trackFileDownloads | Set this to true if you want to enable file download tracking. |
taggedEvents | Set this to true if you want to enable custom event tracking in HTML elements. |
trackLocalhost | Set this to true if you want to enable localhost tracking. |
manualPageviews | Set this to true if you want to disable automatic pageview events. |
pageviewProps | Set the custom properties for pageviews. The event- prefix will be added automatically. See an example. |
revenue | Set this to true if you want to enable ecommerce revenue tracking. |
hash | Set this to true if you want to use hash-based routing. |
exclude | Set this if you want to exclude a set of pages from being tracked. See https://plausible.io/docs/excluding-pages for more details. |
selfHosted | Set this to true if you are self hosting your Plausible instance. Otherwise you will get a 404 when requesting the script. |
enabled | Use this to explicitly decide whether or not to render script. If not passed the script will be rendered in production environments (checking NODE_ENV and VERCEL_ENV). |
integrity | Optionally define the subresource integrity attribute for extra security. |
scriptProps | Optionally override any of the props passed to the script element. See example. |
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
// Important! it is mandatory to pass a config object, even if empty
})
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>
}
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
// Important! it is mandatory to pass a config object, even if empty
})
This will load the script from /yoursubdirectory/js/scriptName.js and fetch it from http://example.com/js/script.js.
Notes:
Proxying will only work if you serve your site using next start. Statically generated sites won't be able to rewrite the requests.
If you are self hosting plausible, you need to set customDomain to your instance otherwise no data will be sent.
Bear in mind that tracking requests will be made to the same domain, so cookies will be forwarded. See https://github.com/4lejandrito/next-plausible/issues/67. If this is an issue for you, from next@13.0.0 you can use middleware to strip the cookies like this:
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',
}
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.
npm run build will generate the production scripts under the dist folder.v3.12.3 (2024-11-01)
FAQs
Simple integration for https://nextjs.org and https://plausible.io analytics.
The npm package next-plausible receives a total of 42,851 weekly downloads. As such, next-plausible popularity was classified as popular.
We found that next-plausible demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.
Security News
vlt's new "reproduce" tool verifies npm packages against their source code, outperforming traditional provenance adoption in the JavaScript ecosystem.