Retext
Architecture Design

Production PostHog Integration for Next.js 15 Prompt

Sets the AI up as a senior next. It's for developers. Use it when short image descriptions keep giving you generic results.

Installs as a snippet — type ;production to paste this prompt anywhere on your Mac.
Prompt Template
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.

Source: awesome-chatgpt-prompts (CC0).

How to use this prompt

  1. 1

    Copy the prompt

    Use the copy button, or type its Retext trigger in any app to paste it.

  2. 2

    Open your AI assistant

    Start a new chat in ChatGPT, Claude, Gemini or the assistant you use.

  3. 3

    Fill in the details

    Replace any [bracketed] parts with your own details.

  4. 4

    Check and refine

    Read the answer, then reply with one change at a time.

Tips for better results

  • •Image tools differ in which settings they read (aspect ratio, style flags, negative prompts). Keep the subject and style lines, and drop settings your tool ignores.
  • •To steer the senior next, add one line after the prompt about your situation: your level, your goal and anything to avoid.
  • •It's a long prompt, so save it as a Retext snippet: type ;production in any app instead of finding and pasting it each time.

Get the free prompt pack

Our best coding prompts in one Markdown file, delivered by email. The templates here stay free either way — the pack just saves you the copying.

Variations

Different style

Keep the subject and composition, and replace the style details with: [style, e.g. watercolor, 35mm film photo, flat vector illustration].

Different format

Add this line: Compose for a [aspect ratio, e.g. 9:16 phone wallpaper] and leave empty space at the [top/bottom] for text.

Context first

Add this line at the end: Before you start, ask me up to three questions about what I need from the senior next and wait for my answers.

Save it as a Retext snippet

Retext is a free text expander for Mac. Save this prompt once, then type ;production in any app (ChatGPT, Claude, your editor, a browser tab) and the full prompt is pasted in.

  1. Click Add to Retext. The prompt installs as a snippet with the trigger ;production.
  2. Change the trigger in Retext if you prefer a different one.
  3. Type the trigger wherever you want the prompt, then fill in the brackets.

Frequently asked questions

What does the Production PostHog Integration for Next.js 15 prompt do?

Sets the AI up as a senior next. It's written for developers.

Which AI tools does it work with?

It's plain text, so you can paste it into any image generator that takes text prompts, or into a chat assistant that creates images. Drop any settings your tool doesn't support.

Can I save this prompt as a snippet?

Yes. Click Add to Retext and it installs as a snippet with the trigger ;production. Type that in any Mac app to paste the full prompt.

Related Templates

Get the free prompt pack

Our best coding prompts in one Markdown file, delivered by email. The templates here stay free either way — the pack just saves you the copying.