Matomo Next
Matomo analytics for Next.js applications
A lightweight, TypeScript-ready Matomo analytics integration for Next.js applications with support for both Pages Router and App Router.
## Features
- ✅ **Pages Router & App Router Support** - Works with both Next.js routing systems
- ✅ **Automatic Page Tracking** - Tracks route changes and page views automatically
- ✅ **Search Tracking** - Built-in search query tracking
- ✅ **GDPR Compliant** - Cookie-less tracking option
- ✅ **Custom Events** - Type-safe event tracking API
- ✅ **A/B Testing** - Built-in support for Matomo's A/B Testing plugin with React hooks
- ✅ **Tag Manager** - Load a Matomo Tag Manager container and push to its data layer
- ✅ **Server-Side Proxy** - Bypass ad-blockers by routing tracking through your own domain
- ✅ **Heatmap & Session Recording** - Optional user behavior visualization
- ✅ **TypeScript Support** - Full type safety and auto-completion
## Installation
```bash
npm install @socialgouv/matomo-next
```
## Quick Start
### Pages Router
Add the [`trackPagesRouter()`](./src/track-pages-router.ts) call in your `_app.js`:
```jsx
import { useEffect } from "react";
import { trackPagesRouter } from "@socialgouv/matomo-next";
const MATOMO_URL = process.env.NEXT_PUBLIC_MATOMO_URL;
const MATOMO_SITE_ID = process.env.NEXT_PUBLIC_MATOMO_SITE_ID;
function MyApp({ Component, pageProps }) {
useEffect(() => {
trackPagesRouter({ url: MATOMO_URL, siteId: MATOMO_SITE_ID });
}, []);
return ;
}
export default MyApp;
```
### App Router
Create a client component for tracking with [`trackAppRouter()`](./src/track-app-router.ts):
```jsx
"use client";
import { trackAppRouter } from "@socialgouv/matomo-next";
import { usePathname, useSearchParams } from "next/navigation";
import { useEffect } from "react";
const MATOMO_URL = process.env.NEXT_PUBLIC_MATOMO_URL;
const MATOMO_SITE_ID = process.env.NEXT_PUBLIC_MATOMO_SITE_ID;
export function MatomoAnalytics() {
const pathname = usePathname();
const searchParams = useSearchParams();
useEffect(() => {
trackAppRouter({
url: MATOMO_URL,
siteId: MATOMO_SITE_ID,
pathname,
searchParams,
});
}, [pathname, searchParams]);
return null;
}
```
Add it to your root layout wrapped in a `Suspense` boundary:
```jsx
import { Suspense } from "react";
import { MatomoAnalytics } from "./matomo";
export default function RootLayout({ children }) {
return (
{children}
);
}
```
## Documentation
- **[Advanced Configuration](docs/advanced.md)** - All configuration options, HeartBeat timer, callbacks, and extensibility
- **[Event Tracking](docs/events.md)** - Track custom user interactions
- **[A/B Testing](docs/ab-testing.md)** - Integrate Matomo's A/B Testing plugin with React hooks
- **[Tag Manager](docs/tag-manager.md)** - Load a Matomo Tag Manager container and push events to it
- **[Server-Side Proxy](docs/server-side-proxy.md)** - Bypass ad-blockers by proxying tracking requests
- **[Heatmap & Session Recording](docs/heatmap-session-recording.md)** - User behavior tracking and visualization
- **[Security & Privacy](docs/security.md)** - CSP configuration and GDPR compliance
## Common Use Cases
### Track Custom Events
Use the [`sendEvent()`](./src/events.ts) helper for type-safe event tracking:
```js
import { sendEvent } from "@socialgouv/matomo-next";
// Track a button click
sendEvent({ category: "contact", action: "click phone" });
// Track with additional context
sendEvent({
category: "video",
action: "play",
name: "intro-video",
value: 120,
});
```
### A/B Testing
Run experiments using Matomo's [A/B Testing plugin](https://plugins.matomo.org/AbTesting). Pass your test definitions to the tracker and use the [`useABTestVariant()`](./src/use-ab-test.ts:32) hook in your components:
```tsx
// Pass abTests to the tracker
trackAppRouter({
url: MATOMO_URL,
siteId: MATOMO_SITE_ID,
pathname,
searchParams,
abTests: [
{
name: "homepage-hero",
percentage: 100,
variations: [{ name: "original" }, { name: "new-hero" }],
},
],
});
```
```tsx
// In your component
import { useABTestVariant } from "@socialgouv/matomo-next";
export function HeroSection() {
const variant = useABTestVariant("homepage-hero");
if (variant === "new-hero") {
return ;
}
return ;
}
```
See the [A/B Testing documentation](docs/ab-testing.md) for scheduling, custom triggers, and advanced usage.
### Server-Side Proxy
Bypass ad-blockers by routing Matomo requests through your own domain using [`withMatomoProxy()`](./src/server-proxy.ts:91):
By default, the public proxy endpoint is generated under your own API namespace: `/api/{random}`.
```js
// next.config.mjs
import { withMatomoProxy } from "@socialgouv/matomo-next";
export default withMatomoProxy({
matomoUrl: "https://analytics.example.com",
})(nextConfig);
```
`matomoUrl` is required here because it’s the **server-side** target the proxy forwards to
(stored in `MATOMO_PROXY_TARGET`, not exposed to the browser).
```tsx
// In your tracker component
import { trackAppRouter } from "@socialgouv/matomo-next";
// When the proxy is configured, calls are automatically routed through your own domain.
// This also hides the usual `matomo.js` / `matomo.php` filenames behind opaque build-time
// random names (some blockers match on those filenames).
trackAppRouter({ siteId: "1", pathname, searchParams });
```
See the [Server-Side Proxy documentation](docs/server-side-proxy.md) for custom paths, chaining with other plugins, and security considerations.
## Configuration Options
| Option | Type | Description | Default | Docs |
| ------------------------------- | -------------------- | ----------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------- |
| `url` | `string` | Matomo instance URL | - | Required unless using the server-side proxy |
| `siteId` | `string` | Matomo site ID | - | Required |
| `useProxy` | `boolean` | Prefer proxy (path + opaque filenames) when available | `true` | Server-side proxy |
| `pathname` | `string` | Current pathname (App Router only) | - | Required for App Router |
| `searchParams` | `URLSearchParams` | URL search params (App Router only) | - | Required for App Router |
| `jsTrackerFile` | `string` | Custom JS tracker filename | `"matomo.js"` (or proxy-provided opaque name) | [Advanced](docs/advanced.md) |
| `phpTrackerFile` | `string` | Custom PHP tracker filename | `"matomo.php"` (or proxy-provided opaque name) | [Advanced](docs/advanced.md) |
| `excludeUrlsPatterns` | `RegExp[]` | URLs to exclude from tracking | `[]` | [Advanced](docs/advanced.md#exclude-url-patterns) |
| `disableCookies` | `boolean` | Cookie-less tracking | `false` | [Advanced](docs/advanced.md#disable-cookies) |
| `cleanUrl` | `boolean` | Remove query params from URLs | `false` | [Advanced](docs/advanced.md#clean-urls) |
| `searchKeyword` | `string` | Search query parameter name | `"q"` | [Advanced](docs/advanced.md#search-tracking) |
| `searchRoutes` | `string[]` | Custom search route paths | `["/recherche", "/search"]` | [Advanced](docs/advanced.md#search-tracking) |
| `enableHeartBeatTimer` | `boolean` | Track time on page | `false` | [Advanced](docs/advanced.md#heartbeat-timer) |
| `heartBeatTimerInterval` | `number` | HeartBeat timer interval (seconds) | `15` (Matomo default) | [Advanced](docs/advanced.md#heartbeat-timer) |
| `enableHeatmapSessionRecording` | `boolean` | Enable session recording | `false` | [Heatmap](docs/heatmap-session-recording.md) |
| `heatmapConfig` | `HeatmapConfig` | Heatmap configuration object | `{}` | [Heatmap](docs/heatmap-session-recording.md) |
| `debug` | `boolean` | Enable debug logs | `false` | [Advanced](docs/advanced.md#debug-mode) |
| `nonce` | `string` | CSP nonce value | - | [Security](docs/security.md) |
| `trustedPolicyName` | `string` | Trusted Types policy name | `"matomo-next"` | [Security](docs/security.md) |
| `onInitialization` | `() => void` | Callback on init | - | [Advanced](docs/advanced.md#extensibility-with-callbacks) |
| `onRouteChangeStart` | `(path) => void` | Callback on route change start | - | [Advanced](docs/advanced.md#extensibility-with-callbacks) |
| `onRouteChangeComplete` | `(path) => void` | Callback on route change complete | - | [Advanced](docs/advanced.md#extensibility-with-callbacks) |
| `onScriptLoadingError` | `() => void` | Callback on script loading error | - | [Advanced](docs/advanced.md#extensibility-with-callbacks) |
| `abTests` | `ABTestDefinition[]` | A/B test experiments to register | - | [A/B Testing](docs/ab-testing.md) |
See [complete configuration options](docs/advanced.md) for full details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Links
- [Matomo Official Documentation](https://matomo.org/docs/)
- [Matomo JavaScript Tracker API](https://developer.matomo.org/api-reference/tracking-javascript)
- [Next.js Documentation](https://nextjs.org/docs)