From 43b948cd63ef7c148360c74918e87d707a6306c3 Mon Sep 17 00:00:00 2001 From: kasin-it Date: Tue, 3 Mar 2026 12:54:50 +0100 Subject: [PATCH 1/2] feat: update docs --- CONTRIBUTING.md | 23 ++++++++++++---- DEPLOYMENT.md | 1 + README.md | 28 ++++++++++++++++---- apps/client-app/README.md | 32 ++++++++-------------- apps/monitor-app/README.md | 38 ++++++++++++++------------- apps/monitor-app/clickhouse/SCHEMA.md | 2 +- packages/client-sdk/README.md | 4 ++- 7 files changed, 77 insertions(+), 51 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 80a487fb..27d33052 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,7 +13,7 @@ Thanks for helping us improve next-cwv-monitor! This guide covers development se ## Requirements -- Node.js ≥ 20 +- Node.js ≥ 24 - pnpm > 10.1 - Docker + Docker Compose @@ -25,9 +25,15 @@ pnpm install pnpm docker:dev ``` -- Brings up ClickHouse and the monitor app, runs migrations, and seeds demo data automatically. -- Monitor: http://localhost:3000 -- Login with credentials from your `.env` file (defaults: `user@example.com` / `password`) +`pnpm docker:dev` starts the full stack via Docker Compose: +- **ClickHouse** — analytics database +- **migrations** — runs ClickHouse schema migrations (short-lived, then exits) +- **monitor-app** — dashboard + ingest API (http://localhost:3000) +- **seed-demo** — seeds demo data on first start + +Login with credentials from your `.env` file (defaults: `user@example.com` / `password`). + +> To also run the demo **client-app** alongside the SDK in watch mode, use `pnpm dev:client` from the repo root (requires the monitor to already be running). ## Coding conventions @@ -56,7 +62,14 @@ Key highlights (see [`CODE_STYLE.md`](./CODE_STYLE.md) for the full guide): ## Commit messages -Use Conventional Commits +Use [Conventional Commits](https://www.conventionalcommits.org/). Examples: + +``` +feat: add hourly aggregates for route breakdowns +fix: correct INP threshold for needs-improvement rating +chore: upgrade ClickHouse client to 1.14 +docs: clarify sampleRate behaviour in SDK README +``` ## Pull requests diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 0c92f319..299c489f 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -34,3 +34,4 @@ docker compose up -d - HTTPS in production (enable SSL mode in setup wizard, or use `AUTH_BASE_URL` with `https://`) - Firewall: only expose ports 80/443 (SSL mode) or `APP_PORT` - `TRUST_PROXY=true` only when behind a trusted proxy (auto-set in SSL mode) +- Change `INITIAL_USER_PASSWORD` from the default before exposing the monitor publicly diff --git a/README.md b/README.md index 55d8e691..97772b02 100644 --- a/README.md +++ b/README.md @@ -43,11 +43,29 @@ Google's Core Web Vitals directly impact your **SEO rankings** and **user experi ## 🚀 Quick Start -**Self-hosting?** Follow the [Deployment Guide](./DEPLOYMENT.md) to run on your infrastructure. +There are two parts: the **monitor** (server that stores and displays metrics) and the **SDK** (snippet you add to your Next.js app). -**Contributing?** See [Contributing Guide](./CONTRIBUTING.md) for local development setup. +> **Prerequisites:** [Node.js](https://nodejs.org/) ≥ 24, [pnpm](https://pnpm.io/) ≥ 10.1, and [Docker](https://www.docker.com/). See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for full setup details. -Add the SDK to the Next.js app you want to monitor: +**Step 1 — Run the monitor** locally: + +```bash +git clone https://github.com/Blazity/next-cwv-monitor.git +cd next-cwv-monitor +cp apps/monitor-app/.env.example apps/monitor-app/.env # defaults work for local dev +pnpm install +pnpm docker:dev +``` + +The dashboard is now running at [http://localhost:3000](http://localhost:3000). See the [Deployment Guide](./DEPLOYMENT.md) for production self-hosting. + +**Step 2 — Create a project** in the monitor dashboard and copy the project UUID. + +**Step 3 — Add the SDK** to the Next.js app you want to monitor: + +```bash +npm install next-cwv-monitor +``` ```tsx // app/providers.tsx — wrap your root layout with this provider @@ -57,8 +75,8 @@ import { CWVMonitor } from "next-cwv-monitor/app-router"; export function Providers({ children }: { children: React.ReactNode }) { return ( {children} diff --git a/apps/client-app/README.md b/apps/client-app/README.md index 9948f664..ffce70dc 100644 --- a/apps/client-app/README.md +++ b/apps/client-app/README.md @@ -1,30 +1,20 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). +# client-app + +A demo Next.js application that uses the `next-cwv-monitor` SDK. It exists to: + +- Demonstrate SDK integration in a realistic Next.js app. +- Generate real CWV events and custom events against the local monitor for development and testing. ## Getting Started -First, run the development server (defaults to port 3001): +From the **repo root** (requires the monitor to already be running via `pnpm docker:dev`): ```bash -pnpm dev +pnpm dev:client ``` -Open [http://localhost:3001](http://localhost:3001) with your browser to see the result. - -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. - -This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. - -## Learn More - -To learn more about Next.js, take a look at the following resources: - -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. - -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! - -## Deploy on Vercel +This starts the client-app on [http://localhost:3001](http://localhost:3001) alongside the SDK in watch mode. See [`CONTRIBUTING.md`](../../CONTRIBUTING.md) for the full development setup. -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. +## SDK integration example -Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details. +See `src/app/providers.tsx` for how `CWVMonitor` is wired up. For full SDK documentation, see [`packages/client-sdk/README.md`](../../packages/client-sdk/README.md). diff --git a/apps/monitor-app/README.md b/apps/monitor-app/README.md index 54d58a62..0c14ed0b 100644 --- a/apps/monitor-app/README.md +++ b/apps/monitor-app/README.md @@ -1,30 +1,32 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). +# monitor-app + +The Next.js dashboard application for next-cwv-monitor. It serves two purposes: + +1. **Ingest API** (`POST /api/ingest`) — receives batched CWV events from the client SDK, validates them, and persists to ClickHouse. +2. **Dashboard UI** — displays Core Web Vitals, route breakdowns, and custom events for all projects. Includes multi-user auth (Better Auth). ## Getting Started -First, run the development server: +The recommended way to run locally is from the **repo root**: ```bash -pnpm dev +pnpm docker:dev ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. - -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. - -This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. - -## Learn More - -To learn more about Next.js, take a look at the following resources: +This starts ClickHouse, runs migrations, seeds demo data, and launches the monitor at [http://localhost:3000](http://localhost:3000). See [`CONTRIBUTING.md`](../../CONTRIBUTING.md) for details. -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. +> If you already have ClickHouse running separately, you can use `pnpm dev` inside this directory instead. -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! +## Stack -## Deploy on Vercel +- **Next.js 16** App Router +- **ClickHouse** — analytics storage +- **Better Auth** — authentication +- **Tailwind CSS + shadcn/ui** — UI -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. +## Further reading -Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details. +- [`ARCHITECTURE.md`](../../ARCHITECTURE.md) — system diagram and component breakdown +- [`DEPLOYMENT.md`](../../DEPLOYMENT.md) — self-hosting guide and environment variables +- [`clickhouse/SCHEMA.md`](./clickhouse/SCHEMA.md) — database schema +- [`CONTRIBUTING.md`](../../CONTRIBUTING.md) — local development setup diff --git a/apps/monitor-app/clickhouse/SCHEMA.md b/apps/monitor-app/clickhouse/SCHEMA.md index 954d9345..0ee69fbc 100644 --- a/apps/monitor-app/clickhouse/SCHEMA.md +++ b/apps/monitor-app/clickhouse/SCHEMA.md @@ -26,7 +26,7 @@ Order key: `(id)` | `route` | String | Normalized route | | `path` | String | Raw concrete path (e.g. `/blog/xyz`) | | `device_type` | LowCardinality(String) | Device classification (`desktop`/`mobile`) | -| `metric_name` | LowCardinality(String) | Metric name (LCP, FID, etc.) | +| `metric_name` | LowCardinality(String) | Metric name (LCP, INP, CLS, etc.) | | `metric_value` | Float64 | Metric value | | `rating` | LowCardinality(String) | Rating (good / needs_improvement / poor) | | `recorded_at` | DateTime64(3, 'UTC') | Client-side timestamp | diff --git a/packages/client-sdk/README.md b/packages/client-sdk/README.md index 0c317dc0..8c7de903 100644 --- a/packages/client-sdk/README.md +++ b/packages/client-sdk/README.md @@ -13,7 +13,9 @@ A lightweight React SDK for monitoring Core Web Vitals and custom events in Next ## Installation npm install next-cwv-monitor - + +> The SDK requires a running instance of the monitor app as your `endpoint`. See the [self-hosting guide](https://github.com/Blazity/next-cwv-monitor/blob/main/DEPLOYMENT.md) to deploy one. + ## Usage From 34a3a9054a8a63a01a872620f1d70490b052b404 Mon Sep 17 00:00:00 2001 From: kasin-it Date: Tue, 3 Mar 2026 13:12:39 +0100 Subject: [PATCH 2/2] fix: update code style examples in CONTRIBUTING.md to use proper text formatting --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 27d33052..2fe8cd30 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,7 +64,7 @@ Key highlights (see [`CODE_STYLE.md`](./CODE_STYLE.md) for the full guide): Use [Conventional Commits](https://www.conventionalcommits.org/). Examples: -``` +```text feat: add hourly aggregates for route breakdowns fix: correct INP threshold for needs-improvement rating chore: upgrade ClickHouse client to 1.14