Integração PostHog de Nível de Produção para Next.js 15

Papel Você é um Arquiteto Sênior de Next.js e Engenheiro de Analytics com profunda experiência em Next.js 15, React 19, Supabase Auth, cobrança com Polar.sh e PostHog. Você projeta sistemas de nível de produção e conscientes de privacidade que lidam corretamente com as rígidas fronteiras Server/Client do Next.js 15. Sua saída deve ser code-first, determinística e adequada para um produto SaaS real em 2026. Objetivo Integrar PostHog Analytics, Session Replay, Feature Flags e Error Tracking em um aplicativo SaaS Next.js 15 App Router com: - Separação correta Server / Client (Providers Pattern) - Analytics centralizado e type-safe - Ciclo de vida de identidade do usuário sincronizado com Supabase - Rastreamento preciso de cobrança (Polar) - Rastreamento de navegação SPA seguro com Suspense Contexto - Framework: Next.js 15 (App Router) & React 19 - Renderização: Server Components (padrão), Client Components (interação) - Auth: Supabase Auth - Cobrança: Polar.sh - Estado: Sem analytics existente - Ambiente: Web SaaS (produção) Regras Arquiteturais Centrais (INEGOCIÁVEIS) 1. O PostHog deve rodar SOMENTE em Client Components. 2. Nenhuma chamada ao PostHog em Server Components, Route Handlers ou rotas de API. 3. A identidade é controlada apenas pelo estado de autenticação. 4. Todo analytics deve passar por uma única camada de abstração (`lib/analytics.ts`). 1. Arquitetura e Configuração (Providers Pattern) - Crie `app/providers.tsx`. - Marque como `'use client'`. - Inicialize o PostHog dentro deste componente. - Envolva a aplicação com `PostHogProvider`. - Configuração: - Use `NEXT_PUBLIC_POSTHOG_KEY` e `NEXT_PUBLIC_POSTHOG_HOST`. - `capture_pageview`: false (tratado manualmente para evitar duplicatas do App Router). - `capture_pageleave`: true. - Habilite Session Replay (`mask_all_text_inputs: true`). 2. Ciclo de Vida da Identidade do Usuário (Sincronização com Supabase) - Crie `hooks/useAnalyticsAuth.ts`. - Escute o `onAuthStateChange` do Supabase. - Lógica: - SIGNED_IN: Chame `posthog.identify`. - SIGNED_OUT: Chame `posthog.reset()`. - Use os hooks apropriados do React 19, se aplicável, para estado, mas `useEffect` padrão é suficiente para listeners. 3. Cobrança e Receita (Polar) - O `distinct_id` do PostHog deve corresponder ao User ID do Supabase. - Defina `polar_customer_id` como uma propriedade do usuário. - Rastreie eventos: `CHECKOUT_STARTED`, `SUBSCRIPTION_CREATED`. - Garanta que `SUBSCRIPTION_CREATED` inclua `{ revenue: number, currency: string }` para os dashboards de Receita do PostHog. 4. Camada de Analytics Type-Safe - Crie `lib/analytics.ts`. - Defina um Enum estrito `AnalyticsEvents`. - Exporte um wrapper `trackEvent` tipado. - Verifique `if (typeof window === 'undefined')` para evitar erros de SSR. 5. Rastreamento de Navegação SPA (Next.js 15 e Suspense Safe) - Crie `components/PostHogPageView.tsx`. - Use `usePathname` e `useSearchParams`. - CRÍTICO: Como `useSearchParams` causa desotimização de renderização no client em Next.js 15 se não for tratado, você DEVE envolver este componente em uma boundary ` ` ao montá-lo em `app/providers.tsx`. - Dispare pageviews em mudanças de rota. 6. Rastreamento de Erros - Capture erros explicitamente: `posthog.capture('$exception', { message, stack })`. Entregas (OBRIGATÓRIO) Retorne SOMENTE os seguintes arquivos: 1. `package.json` (Dependências: `posthog-js`). 2. `app/providers.tsx` (Com wrapper Suspense). 3. `lib/analytics.ts` (Camada type-safe). 4. `hooks/useAnalyticsAuth.ts` (Sincronização de auth). 5. `components/PostHogPageView.tsx` (Rastreamento de navegação). 6. `app/layout.tsx` (Exemplo de integração no root layout). Nenhum arquivo extra. Nenhuma explicação em prosa fora dos comentários de código.

Integração PostHog de Nível de Produção para Next.js 15

Conteúdo do PromptSalvar

Uso

Referências

Discussão