next-plausible

next-plausible wires Plausible Analytics into a Next.js application with minimal setup: a PlausibleProvider component injects the tracking script at the app or page level, and a withPlausibleProxy config wrapper rewrites the script and API endpoint through your own domain to reduce ad-blocker interference. It supports the Pages Router, the App Router, and both server-rendered and statically generated sites.

Beyond pageview tracking, the package exposes a usePlausible hook for firing custom events from client components, with optional TypeScript generics to type-check event names and their properties at compile time.

What You Get

• A PlausibleProvider component for injecting the Plausible script in _app, a page, or the App Router root layout
• A withPlausibleProxy Next.js config wrapper that proxies the script and event API through your own domain
• A usePlausible hook for sending custom events, with optional generic typing of event names and properties
• Support for Plausible init options like custom properties, file-download tracking, and hash-based routing
• Configurable proxy paths and script props for advanced deployment setups

Common Use Cases

• Adding privacy-friendly, cookie-free analytics to a Next.js marketing site or app
• Proxying the analytics script through a first-party path to avoid ad-blocker false positives
• Tracking custom conversion events (signups, button clicks) from client components with type-checked event names
• Migrating a Next.js site from Google Analytics to a lighter, GDPR-friendly alternative

Under The Hood

Architecture - The package is a thin adapter split across three files: lib/PlausibleProvider.tsx renders the Plausible script tag and reads environment context to decide whether tracking is enabled, lib/usePlausible.ts exposes a hook that reads the injected window.plausible function, and lib/withPlausibleProxy.ts wraps a Next.js config object to add rewrites for the proxied script and API paths. Tech Stack - Written in TypeScript, built with tsc plus Rollup into CJS/ESM/type-declaration bundles, tested with Jest and Testing Library across a matrix of proxy configurations (custom domain, base path, trailing slash, App Router) under the test/ directory. Code Quality - The core logic is intentionally small (about 240 lines across the three lib files) with an extensive integration test suite covering proxy edge cases (locale, cookies, sub-paths), though the core provider/hook files themselves have no dedicated unit tests beyond the proxy fixtures. API Design - The public API is minimal and idiomatic React/Next.js: a provider component, one hook, and one config-wrapping function, with TypeScript generics available to type custom event props, keeping the learning curve low for anyone already familiar with Next.js conventions.