Intégration PostHog pour Next.js App Router

Cette skill vous aide à ajouter des analyses PostHog à des applications Next.js App Router.

Workflow

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

1. basic-integration-1.0-begin.md - Configuration PostHog - Début ← Commencez ici
2. basic-integration-1.1-edit.md - Configuration PostHog - Édition
3. basic-integration-1.2-revise.md - Configuration PostHog - Révision
4. basic-integration-1.3-conclude.md - Configuration PostHog - Conclusion

Fichiers de référence

• references/EXAMPLE.md - Exemple de code projet Next.js App Router
• references/next-js.md - Next.js - docs
• references/identify-users.md - Identifier les utilisateurs - docs
• references/basic-integration-1.0-begin.md - Configuration PostHog - début
• references/basic-integration-1.1-edit.md - Configuration PostHog - édition
• references/basic-integration-1.2-revise.md - Configuration PostHog - révision
• references/basic-integration-1.3-conclude.md - Configuration PostHog - conclusion

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

Principes clés

• Variables d'environnement : Utilisez toujours les variables d'environnement pour les clés PostHog. Ne les codez jamais en dur.
• Changements minimaux : Ajoutez le code PostHog à côté des intégrations existantes. Ne remplacez pas ou ne restructurez pas le code existant.
• Correspondre à l'exemple : Votre implémentation devrait suivre les motifs du projet exemple aussi étroitement que possible.

Directives du framework

• Pour Next.js 15.3+, initialisez PostHog dans instrumentation-client.ts pour la configuration la plus simple
• Pour les feature flags, utilisez les hooks useFeatureFlagEnabled() ou useFeatureFlagPayload() - ils gèrent automatiquement les états de chargement et la synchronisation externe
• Ajoutez la capture d'analyses dans les gestionnaires d'événements où se produisent les actions utilisateur, NON dans useEffect réagissant à des changements d'état
• N'utilisez PAS useEffect pour la transformation de données - calculez les valeurs dérivées lors du rendu
• N'utilisez PAS useEffect pour répondre aux événements utilisateur - mettez cette logique directement dans le gestionnaire d'événement
• N'utilisez PAS useEffect pour chaîner les mises à jour d'état - calculez toutes les mises à jour connexes ensemble dans le gestionnaire d'événement
• N'utilisez PAS useEffect pour notifier les composants parents - appelez le callback parent aux côtés de setState dans le gestionnaire d'événement
• Pour réinitialiser l'état du composant lors d'un changement de prop, passez la prop comme clé du composant au lieu d'utiliser useEffect
• useEffect est UNIQUEMENT pour la synchronisation avec les systèmes externes (widgets non-React, APIs du navigateur, souscriptions réseau)

Identification des utilisateurs

Identifiez les utilisateurs lors des événements de connexion et d'inscription. Reportez-vous au code exemple et à la documentation pour le motif d'identification correct pour ce framework. Si du code frontend et backend existent tous deux, transmettez la session côté client et l'ID distinct en utilisant les en-têtes X-POSTHOG-DISTINCT-ID et X-POSTHOG-SESSION-ID pour maintenir la corrélation.

Suivi des erreurs

Ajoutez le suivi des erreurs PostHog aux fichiers pertinents, en particulier autour des flux utilisateur critiques et des limites de l'API.