Intégration PostHog pour Next.js Pages Router

Cette skill vous aide à ajouter PostHog analytics à vos applications Next.js Pages Router.

Workflow

Suivez ces étapes dans l'ordre pour compléter l'intégration :

1. basic-integration-1.0-begin.md - PostHog Setup - Begin ← Commencez ici
2. basic-integration-1.1-edit.md - PostHog Setup - Edit
3. basic-integration-1.2-revise.md - PostHog Setup - Revise
4. basic-integration-1.3-conclude.md - PostHog Setup - Conclusion

Fichiers de référence

• references/EXAMPLE.md - Exemple de code de projet Next.js Pages Router
• references/next-js.md - Next.js - docs
• references/identify-users.md - Identify users - docs
• references/basic-integration-1.0-begin.md - PostHog setup - begin
• references/basic-integration-1.1-edit.md - PostHog setup - edit
• references/basic-integration-1.2-revise.md - PostHog setup - revise
• references/basic-integration-1.3-conclude.md - PostHog setup - conclusion

Le projet exemple montre le pattern d'implémentation cible. Consultez la documentation pour les détails d'API.

Principes clés

• Variables d'environnement : Toujours utiliser les variables d'environnement pour les clés PostHog. Ne jamais les hardcoder.
• Changements minimalistes : Ajouter le code PostHog aux côtés des intégrations existantes. Ne pas remplacer ou restructurer le code existant.
• Suivre l'exemple : Votre implémentation doit suivre les patterns du projet exemple aussi fidèlement que possible.

Directives du framework

• Pour Next.js 15.3+, initialiser PostHog dans instrumentation-client.ts pour la configuration la plus simple
• Pour les feature flags, utiliser les hooks useFeatureFlagEnabled() ou useFeatureFlagPayload() - ils gèrent automatiquement les états de chargement et la synchronisation externe
• Ajouter la capture analytics dans les event handlers où les actions utilisateur se produisent, PAS dans useEffect réagissant à des changements d'état
• NE PAS utiliser useEffect pour la transformation de données - calculer les valeurs dérivées pendant le rendu à la place
• NE PAS utiliser useEffect pour répondre aux événements utilisateur - mettre cette logique dans le event handler lui-même
• NE PAS utiliser useEffect pour chaîner les mises à jour d'état - calculer toutes les mises à jour connexes ensemble dans le event handler
• NE PAS utiliser useEffect pour notifier les composants parents - appeler le callback parent aux côtés de setState dans le event handler
• Pour réinitialiser l'état d'un composant quand une prop change, passer la prop comme key du composant au lieu d'utiliser useEffect
• useEffect est UNIQUEMENT pour synchroniser avec des systèmes externes (widgets non-React, APIs navigateur, subscriptions réseau)

Identifier les utilisateurs

Identifier les utilisateurs lors des événements de connexion et d'inscription. Référez-vous au code exemple et à la documentation pour le pattern d'identification correct pour ce framework. Si du code frontend et backend existe, passer la session côté client et l'ID distinct en utilisant les headers X-POSTHOG-DISTINCT-ID et X-POSTHOG-SESSION-ID pour maintenir la corrélation.

Suivi des erreurs

Ajouter le suivi des erreurs PostHog aux fichiers pertinents, particulièrement autour des flux utilisateur critiques et des limites d'API.