next-plausible: a Plausible analytics provider for Next.js apps

The problem: analytics that survives an ad blocker

Plausible is a privacy focused analytics product, and the way it is normally installed is a single script tag pointing at a plausible.io URL. That approach has one well known failure mode: the request goes to a domain an ad blocker recognises, and the script never loads, so your numbers quietly undercount. Plausible's own recommendation is to proxy the script from your own domain, which removes the tell. next-plausible exists to make that pattern, plus the rest of the plumbing, a drop-in for Next.js. The repository description is exactly that: a simple integration for nextjs.org and plausible.io analytics, and there is a live demo at next-plausible.vercel.app plus a linked real world commit in another repository to show it in use. The primary language is TypeScript, the licence is MIT, and the package is published on npm as next-plausible.

PlausibleProvider is the whole public surface

The package exposes a single component that you place at the top of your application. In the pages router that means wrapping your app in pages/_app.js, and the README gives the whole file.

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

The src prop is the site specific script URL you copy from your Plausible dashboard, which the README shows in the shape https://plausible.io/js/pa-XXXXX.js. Two other entry points matter. If you only want analytics on one page, you can wrap that page in a PlausibleProvider directly instead of the whole app, and the README gives the page level example. If you are using the app directory, the provider goes inside the root layout, wrapping the children, and the README shows that variant with a RootLayout function. The component itself is what enables the script, and the props table explains how it decides whether to render: the enabled prop lets you decide explicitly, and if it is not passed the script is rendered in production environments, with NODE_ENV and VERCEL_ENV being the checks the README names.

The prop surface and the init options it forwards

The provider takes five props, and each one maps to a specific behaviour. src is the script URL and is not required when the proxy is used. init is an object of options passed straight through to plausible.init(), and that is where the interesting configuration lives: customProperties as an object or a function, endpoint for a custom tracking endpoint which the proxy sets automatically, fileDownloads to track only certain file types such as pdf, hashBasedRouting to turn on hash based routing, autoCapturePageviews to set to false and disable automatic pageview events, and captureOnLocalhost to enable localhost tracking. The integrity prop adds a subresource integrity attribute for extra security, and scriptProps overrides any of the props passed to the script element, with the README pointing at a test file example for that case. The design is a thin pass-through rather than a reimplementation: the package does not wrap the Plausible API in a new abstraction, it forwards what you give it.

Proxying the script through next.config.js

The proxy is the part that addresses the ad blocker problem, and it is implemented as a config wrapper rather than a component. You wrap your next.config.js export in withPlausibleProxy and pass the script URL.

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

module.exports = withPlausibleProxy({
  src: 'https://plausible.io/js/pa-XXXXX.js',
})({
  // ...your next js config, if any
  // Important! it is mandatory to pass a config object, even if empty
})

The wrapper sets up the necessary rewrites and configures PlausibleProvider to use the local proxy URLs automatically, which is why the src prop is not required once the proxy is active and the provider can be used bare. You can also override the local paths for the proxied script and the API endpoint, with scriptPath and apiPath, and the defaults are /js/script.js and /api/event, which the README notes match Plausible's recommended proxy paths. The second configuration block in the README is the same call with those two extra keys, and the comment inside it is worth repeating because it is an easy trap: a config object must be passed even if it is empty.

Static exports, self hosting and the cookie question

Three notes in the README define the boundaries of the proxy approach, and they are the ones to read before you commit. The first is that proxying only works if you serve your site with next start, because statically generated sites cannot rewrite the requests. If your deployment is a static export, the proxy is not available to you and you are back to the direct script URL. The second is self hosting: if you run Plausible yourself, you use your instance URL as src. The third is cookies, and it is the most consequential. Because tracking requests are made to the same domain, cookies are forwarded, and the README links an issue about it. The documented workaround is a Next.js middleware that strips the cookie header for the proxy path, and the README notes that from [email protected] you can use middleware to set headers, with a matcher of /proxy/api/event and a requestHeaders.set('cookie', '') call. That is a real behavioural consequence of self-hosting the script under your own domain, and one you should decide on rather than inherit.

Package layout, peer ranges and the build

The repository is a small library with a demo, and the package.json describes the shape precisely. The published version is 4.0.0, and only dist is shipped, with main pointing at dist/index.js, module at dist/index.esm.js and types at dist/index.d.ts, so consumers get CommonJS, ESM and type declarations from one package. The peer dependencies are the important part: next from 11.1.0 up to 16.0.0, and react and react-dom from 16.8.0 through 19.0.0, with a note in the README that on a Next version lower than 11.1.0 you should use next-plausible@2 to avoid type checking errors, linking to the relevant issue. The scripts show the toolchain: the build runs tsc and then rollup, the test script is jest, and prepare installs husky for the git hooks, with lint-staged running prettier over JavaScript, TypeScript, Markdown and style files. The source lives in index.ts and lib/, with the test/ directory and a rollup.config.js, and a demo/ folder containing its own Next.js app with tailwind and postcss configuration.

Version history, maintenance and where it fits

The repository has no GitHub releases at all, so versioning is read from package.json and the CHANGELOG.md in the tree, and the current version is 4.0.0. The README points at a MIGRATION.md for anyone upgrading from v3, which is the sign of a package that has changed its public shape at least once. On maintenance, the repository is not archived and the last push was on 2026-04-03, so the code has not moved for some months. That is a reasonable signal for a stable integration package, but it is not the same as an actively developed one, and the README gives no statement about support commitments. The alternative approach is worth naming explicitly, because it is the honest comparison. Instead of this package you can insert the Plausible script tag yourself in a Next.js layout or component, which is a few lines of code and no dependency, and Plausible's own script and proxy documentation covers that path. What you give up is the provider abstraction, the forwarded init options, the proxy rewrites and the environment checks. What you get in return is one fewer dependency to track, and no coupling to the peer version ranges above.

Editorial conclusion

Adopt next-plausible if your Next.js application needs privacy friendly analytics with a React provider, event options and a proxy path, and you are willing to depend on a single community maintained package rather than a hosted product. Do not adopt it for a statically exported site that needs the script proxy, since the README states proxying only works when you serve with next start, and do not expect it to replace a cookie consent flow or a server side event pipeline. Before you install, check which Next.js major your app uses against the peer dependency range, read MIGRATION.md if you are coming from v3, and decide whether the cookie forwarding behaviour of the proxy is acceptable for your privacy posture.

Frequently asked questions

Official sources

1. 4lejandrito/next-plausible on GitHub
2. Issues
3. License: MIT
4. Project website
5. README