next-cwv-monitor

Self-hosted Core Web Vitals monitoring for Next.js: collect performance data from real users, correlate metrics with conversion events, and see data in real-time. Free & open source.

Quick Start • Features • Installation • FAQ • Contributing

🎯 Overview

Google's Core Web Vitals directly impact your SEO rankings and user experience. Yet existing monitoring solutions are either expensive, lack deep Next.js integration, or don't provide route-level insights.

next-cwv-monitor is a free, self-hosted alternative purpose-built for Next.js developers:

• 🏠 Self-hosted — Your data stays on your infrastructure, no vendor lock-in
• 📊 Real User Monitoring — Capture LCP, INP, CLS, TTFB, and FCP from actual visitors
• 🎯 Custom Events — Correlate CWV with conversions, purchases, signups
• ⚡ Lightweight SDK — <5 kB gzipped, zero impact on your app's performance
• 🔒 Privacy-first — No cookies, no personal data, GDPR-compliant by design

🚀 Quick Start

Self-hosting? Follow the Deployment Guide to run on your infrastructure.

Contributing? See Contributing Guide for local development setup.

Add the SDK to the Next.js app you want to monitor:

// app/providers.tsx — wrap your root layout with this provider
"use client";
import { CWVMonitor } from "next-cwv-monitor/app-router";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CWVMonitor
      projectId="YOUR_PROJECT_UUID" // From the dashboard
      endpoint="http://localhost:3000"
    >
      {children}
    </CWVMonitor>
  );
}

💡 Using Pages Router? Import from next-cwv-monitor/pages-router instead and wrap your _app.tsx. See SDK docs for details.

That's it! Your app will start sending CWV metrics 🎉

✨ Features

• 📊 Real User Monitoring — Capture LCP, INP, CLS, TTFB, and FCP from actual visitors
• 🛤️ Next.js Router Integration — Automatic route detection and normalization (/blog/[slug])
• 📱 Device Segmentation — Filter metrics by desktop vs. mobile
• 📈 Percentile Analysis — View p50, p75, p90, p95, p99 distributions
• 🎯 Custom Events — Track business events and correlate with web vitals
• 👁️ Page Views — Automatic tracking for conversion analysis
• 🎛️ Multi-project — Monitor all your Next.js apps from one dashboard
• 🔐 Multi-tenant Auth — Role-based access control with Better Auth
• 🔄 App & Pages Router — Full support for both Next.js routing paradigms
• ⚡ Lightweight SDK — <5 kB gzipped, tree-shakeable, router-specific entrypoints
• 📡 Smart Batching — Efficient event delivery with automatic flush on idle/unload
• 🚀 ClickHouse Backend — Blazing fast analytics on billions of events

📸 Screenshots

Dashboard Overview

Dashboard overview showing CWV metrics across all routes

Route Detail View

Drill down into individual routes with percentile distributions

Custom Events

Track custom business events correlated with Core Web Vitals

📦 Installation

Run the interactive setup wizard:

curl -fsSL https://raw.githubusercontent.com/Blazity/next-cwv-monitor/main/setup.sh | bash

The wizard downloads Docker Compose files, guides you through configuration (including optional SSL), and generates secure secrets automatically.

📖 For complete deployment options, see DEPLOYMENT.md.

❓ FAQ

Why self-host CWV monitoring?

Self-hosting gives you full data ownership, no per-seat pricing, custom event correlation with business metrics, and the flexibility to run on your own infrastructure with no external dependencies.

What's the performance impact of the SDK?

The SDK is designed to be lightweight with tree-shakeable router-specific entrypoints. Events are batched and sent asynchronously using sendBeacon for reliable delivery without blocking navigation.

How long is data retained?

Default retention: Raw events — 90 days, Daily aggregates — 365 days. Older data is automatically cleaned up by ClickHouse TTL.

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for development setup, coding guidelines, and how to submit pull requests.

📄 License

This project is MIT licensed.

---

_{Built with ❤️ by Blazity}