Next.js + Supabase + PulseKit Starter

The fastest way to build apps with Next.js, Supabase, and privacy-friendly analytics

Features · Demo · Deploy to Vercel · Clone and Run Locally · Project Structure

This template extends the official Next.js Supabase Starter with PulseKit — a lightweight, privacy-friendly analytics toolkit that stores all data in your own Supabase database.

Features

• Next.js App Router — works across Server Components, Client Components, Route Handlers, Server Actions, and Middleware
• Supabase Auth — cookie-based authentication via @supabase/ssr, with password-based auth from the Supabase UI Library
• PulseKit Analytics — automatic page view tracking, Web Vitals (LCP, INP, CLS, FCP, TTFB), error reporting, and geo-location stats
• Analytics Dashboard — built-in dashboard at /admin/analytics with password-protected access
• Data Lifecycle — automatic aggregation and cleanup of old raw events to keep your database lean
• Security Hardened — RLS policies with minimum-privilege grants per role, validated event types on insert
• Tailwind CSS + shadcn/ui — styled with Tailwind CSS and shadcn/ui components

Demo

You can view a fully working demo at https://with-supabase-pulsekit-template.vercel.app/.

Deploy to Vercel

Vercel deployment will guide you through creating a Supabase account and project. After installation of the Supabase integration, all relevant environment variables will be assigned to the project so the deployment is fully functioning.

After deploying, you will still need to:

1. Set the PULSE_SECRET environment variable in Vercel (a 16+ character password for your analytics dashboard)
2. Set the SUPABASE_SERVICE_ROLE_KEY environment variable in Vercel
3. Run the database migrations (see below)

Clone and Run Locally

1. Create a Supabase project

Create a new project via the Supabase dashboard.

2. Clone the repository

git clone https://github.com/benoiteom/with-supabase-pulsekit.git
cd with-supabase-pulsekit
npm install

3. Set up environment variables

Rename .env.example to .env.local and fill in the values:

NEXT_PUBLIC_SUPABASE_URL=your-project-url
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-publishable-or-anon-key
PULSE_SECRET=your-analytics-dashboard-password
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

Note

NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY can be found in your Supabase project's API settings. SUPABASE_SERVICE_ROLE_KEY is in the same place under "Service Role". PULSE_SECRET is a password you create (16+ characters) to protect your analytics dashboard.

4. Run database migrations

Link your Supabase project and push the PulseKit schema:

npx supabase link
npx supabase db push

This creates the analytics schema with tables for events and aggregates, plus RPC functions for querying stats.

5. Start the development server

npm run dev

The app should now be running on localhost:3000.

Project Structure

├── app/
│   ├── admin/analytics/     # PulseKit analytics dashboard (password-protected)
│   ├── api/pulse/           # Analytics API routes (ingestion, auth, aggregation, cleanup)
│   ├── auth/                # Supabase auth pages (login, sign-up, callback, etc.)
│   └── protected/           # Example protected page
├── components/
│   ├── pulse-tracker-wrapper.tsx  # PulseKit tracker (auto page views, vitals, errors)
│   └── tutorial/            # Setup guide shown on the home page
├── instrumentation.ts       # Server-side error reporting via PulseKit
├── lib/supabase/            # Supabase client helpers and middleware proxy
└── supabase/migrations/     # SQL migrations for the analytics schema

How PulseKit Works in This Template

• Tracking — PulseTrackerWrapper in the root layout automatically captures page views, Web Vitals, and client-side errors. No manual instrumentation needed.
• Server Errors — instrumentation.ts uses createPulseErrorReporter to capture server-side errors via Next.js's onRequestError hook.
• Ingestion — Events are sent to /api/pulse which writes them to the analytics.pulse_events table in Supabase.
• Dashboard — /admin/analytics renders the PulseDashboard component, protected by PulseAuthGate (uses PULSE_SECRET).
• Data Lifecycle — /api/pulse/consolidate rolls old raw events into daily aggregates and cleans up, keeping your database lean.

Feedback and Issues

• PulseKit: github.com/benoiteom/pulsekit/issues
• Supabase: github.com/supabase/supabase/issues