InnerVault

Production-Grade PostHog Integration for Next.js 15 (App Router)

Indexedprompts.chat (CC0 prompt collection), Ted2xmen

Production-Grade PostHog Integration for Next.js 15 (App Router) Role You are a Senior Next.js Architect & Analytics Engineer with deep expertise in Next.js 15, React 19, Supabase Auth, Polar.sh billing, and PostHog…

Open the source (opens github.com) https://github.com/f/prompts.chat

What it is

Prompts from Ted2xmen.

The problem it solves and who it suits haven't been reviewed by InnerVault. The description above is the source's own.

The prompt

Production-Grade PostHog Integration for Next.js 15 (App Router)
Role
You are a Senior Next.js Architect & Analytics Engineer with deep expertise in Next.js 15, React 19, Supabase Auth, Polar.sh billing, and PostHog.
You design production-grade, privacy-aware systems that handle the strict Server/Client boundaries of Next.js 15 correctly.
Your output must be code-first, deterministic, and suitable for a real SaaS product in 2026.

Goal
Integrate PostHog Analytics, Session Replay, Feature Flags, and Error Tracking into a Next.js 15 App Router SaaS application with:
- Correct Server / Client separation (Providers Pattern)
- Type-safe, centralized analytics
- User identity lifecycle synced with Supabase
- Accurate billing tracking (Polar)
- Suspense-safe SPA navigation tracking

Context
- Framework: Next.js 15 (App Router) & React 19
- Rendering: Server Components (default), Client Components (interaction)
- Auth: Supabase Auth
- Billing: Polar.sh
- State: No existing analytics
- Environment: Web SaaS (production)

Core Architectural Rules (NON-NEGOTIABLE)
1. PostHog must ONLY run in Client Components.
2. No PostHog calls in Server Components, Route Handlers, or API routes.
3. Identity is controlled only by auth state.
4. All analytics must flow through a single abstraction layer (`lib/analytics.ts`).

1. Architecture & Setup (Providers Pattern)
- Create `app/providers.tsx`.
- Mark it as `'use client'`.
- Initialize PostHog inside this component.
- Wrap the application with `PostHogProvider`.
- Configuration:
  - Use `NEXT_PUBLIC_POSTHOG_KEY` and `NEXT_PUBLIC_POSTHOG_HOST`.
  - `capture_pageview`: false (Handled manually to avoid App Router duplicates).
  - `capture_pageleave`: true.
  - Enable Session Replay (`mask_all_text_inputs: true`).

2. User Identity Lifecycle (Supabase Sync)
- Create `hooks/useAnalyticsAuth.ts`.
- Listen to Supabase `onAuthStateChange`.
- Logic:
  - SIGNED_IN: Call `posthog.identify`.
  - SIGNED_OUT: Call `posthog.reset()`.
  - Use appropriate React 19 hooks if applicable for state, but standard `useEffect` is fine for listeners.

3. Billing & Revenue (Polar)
- PostHog `distinct_id` must match Supabase User ID.
- Set `polar_customer_id` as a user property.
- Track events: `CHECKOUT_STARTED`, `SUBSCRIPTION_CREATED`.
- Ensure `SUBSCRIPTION_CREATED` includes `{ revenue: number, currency: string }` for PostHog Revenue dashboards.

4. Type-Safe Analytics Layer
- Create `lib/analytics.ts`.
- Define strict Enum `AnalyticsEvents`.
- Export typed `trackEvent` wrapper.
- Check `if (typeof window === 'undefined')` to prevent SSR errors.

5. SPA Navigation Tracking (Next.js 15 & Suspense Safe)
- Create `components/PostHogPageView.tsx`.
- Use `usePathname` and `useSearchParams`.
- CRITICAL: Because `useSearchParams` causes client-side rendering de-opt in Next.js 15 if not handled, you MUST wrap this component in a `<Suspense>` boundary when mounting it in `app/providers.tsx`.
- Trigger pageviews on route changes.

6. Error Tracking
- Capture errors explicitly: `posthog.capture('$exception', { message, stack })`.

Deliverables (MANDATORY)
Return ONLY the following files:
1. `package.json` (Dependencies: `posthog-js`).
2. `app/providers.tsx` (With Suspense wrapper).
3. `lib/analytics.ts` (Type-safe layer).
4. `hooks/useAnalyticsAuth.ts` (Auth sync).
5. `components/PostHogPageView.tsx` (Navigation tracking).
6. `app/layout.tsx` (Root layout integration example).

🚫 No extra files.
🚫 No prose explanations outside code comments.

Written by the prompts.chat (CC0 prompt collection) community (Ted2xmen). Not tested by InnerVault.

How to get it

Setup steps: not applicable.

Related

  1. Create Project

    Prompts

    MASTER AI SOFTWARE DEVELOPMENT PROMPT District Administration — Generic Campaign Management, Field Operations, Survey, Verification, Reporting & Payment Platform Build a production-grade, full-stack, enterprise-level…

    Indexed prompts.chat (CC0 prompt collection), maarifkhatri91@gmail.com CC0-1.0

  2. Web Typography

    Prompts

    --- name: web-typography description: Generate production-grade web typography CSS with correct sizing, spacing, font loading, and responsive behavior based on Butterick's Practical Typography --- <role> You are a…

    Indexed prompts.chat (CC0 prompt collection), c.aksan@gmail.com CC0-1.0

  3. # API Tester You are a senior API testing expert and specialist in performance testing, load simulation, contract validation, chaos testing, and monitoring setup for production-grade APIs. ## Task-Oriented Execution…

    Indexed prompts.chat (CC0 prompt collection), wkaandemir CC0-1.0

  4. Act as a Senior Flutter Architect + Product Engineer. You have over 10 years of experience building production-grade Flutter apps for Android and iOS, focusing on clean architecture, great UX, strong privacy, and fast…

    Indexed prompts.chat (CC0 prompt collection), yigitgurler CC0-1.0

  5. You are a senior product designer operating at Apple-level design standards (2026). Your task is to transform a given idea into a clean, professional, production-grade UI system. Avoid generic, AI-generated aesthetics…

    Indexed prompts.chat (CC0 prompt collection), mmanisaligil CC0-1.0

  6. Act as a Senior Mobile Performance Engineer and Supabase Edge Functions Architect. Your task is to perform a deep, production-grade analysis of this codebase with a strict focus on: - Expo (React Native) mobile app…

    Indexed prompts.chat (CC0 prompt collection), Ted2xmen CC0-1.0